For AI agents: a Markdown version of this page is at https://docs.snowplow.io/tutorials/tracking-as-code/local-setup.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt.
Define the tracking in your repository
In this part of the tutorial, you'll add the tracking definitions to your application's repository and generate the tracking code from them. Everything on this page runs on your machine without Console credentials.
The repository holds the definitions in the format Snowplow CLI reads and writes: data structures under data-structures/, and the tracking plan and its source application under data-products/. Work on a feature branch created from develop:
git switch develop
git switch -c feature/signup-tracking
Add the data structures
Create one file per data structure, under a directory named after the vendor. The event signup records how the user created an account:
apiVersion: v1
resourceType: data-structure
meta:
hidden: false
schemaType: event
customData: {}
data:
$schema: http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#
self:
vendor: com.example
name: signup
format: jsonschema
version: 1-0-0
type: object
description: Someone created an account on the web app
properties:
method:
type: string
description: How the account was created
enum:
- email
- google
- github
required:
- method
additionalProperties: false
The entity plan records the pricing plan the user picked:
apiVersion: v1
resourceType: data-structure
meta:
hidden: false
schemaType: entity
customData: {}
data:
$schema: http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#
self:
vendor: com.example
name: plan
format: jsonschema
version: 1-0-0
type: object
description: The pricing plan the account is on
properties:
name:
type: string
description: The name of the plan
maxLength: 64
required:
- name
additionalProperties: false
The meta.schemaType field marks each data structure as an event or an entity. For every field in the file, and for snowplow-cli ds generate, which writes a new file for you, see Snowplow CLI data structures.
Add the source application and the tracking plan
The source application lists the app IDs your web app sends events with:
apiVersion: v1
resourceType: source-application
resourceName: 00000000-0000-4000-8000-000000000001
data:
name: Web app
description: The web app
appIds:
- web-app
entities:
tracked: []
enriched: []
The tracking plan references the source application and holds one event specification. The event specification names the event and the entity it carries, with version: 0, because Console starts a new event specification at version 0:
apiVersion: v1
resourceType: data-product
resourceName: 00000000-0000-4000-8000-000000000002
data:
name: Signup flow
description: Signups on the web app
sourceApplications:
- $ref: ./source-apps/web-app.yaml
eventSpecifications:
- resourceName: 00000000-0000-4000-8000-000000000003
name: Signup
version: 0
description: Someone created an account and picked a plan
event:
source: iglu:com.example/signup/jsonschema/1-0-0
entities:
tracked:
- source: iglu:com.example/plan/jsonschema/1-0-0
minCardinality: 1
maxCardinality: 1
Each resourceName must be a UUID v4 of your own. Snowplow CLI can write the files with new ids for you, and you then fill in the fields shown above, including version: 0:
snowplow-cli dp generate --source-app "Web app" --data-product "Signup flow"
snowplow-cli dp add-event-spec -e Signup data-products/signup-flow.yaml
The version field is what lets Snowplow CLI check every change against the version Console assigns, as described in Declare event specification versions.
If the tracking plan already exists in Console, start from Console's copy instead. snowplow-cli dp download --versions writes every tracking plan and source application in your organization, with the versions Console holds, so keep only the files for this tracking plan.
Configure Snowtype
Snowtype can generate code from what's in Console or from files in a repository. This tutorial uses the repository, so point Snowtype at the two directories in snowtype.config.json. With localDataProducts set, and no dataStructures, eventSpecificationIds, or dataProductIds, Snowtype reads only the repository and doesn't need Console credentials:
{
"tracker": "@snowplow/browser-tracker",
"language": "typescript",
"outpath": "src/tracking",
"repositories": ["data-structures"],
"localDataProducts": ["data-products"],
"igluCentralSchemas": [],
"dataStructures": [],
"eventSpecificationIds": [],
"dataProductIds": []
}
For what Snowtype reads from each file, see Local tracking plans.
Generate the tracking code
Generate the code from the repository files:
npx snowtype generate
Snowtype warns that it doesn't check the schemas against the environments they're deployed to, because it doesn't contact Console:
✔: Valid configuration found
⚠ Warning: Generating from local definitions only. Schemas are not checked against the environments they are deployed to.
✔: Code generated, writing...
Snowtype writes src/tracking/snowplow.ts. Call the event specification's function where the signup happens, passing the plan as an entity:
import { trackSignupSpec, createPlan } from './tracking/snowplow';
trackSignupSpec({
method: 'email',
context: [createPlan({ name: 'free' })],
});
The function attaches the event specification's ID and version to every event, so Snowplow can match the event to its specification.
Commit the generated file together with the definitions. Later, npx snowtype check confirms that the committed code still matches what snowtype generate writes:
✔: Valid configuration found
⚠ Warning: Generating from local definitions only. Schemas are not checked against the environments they are deployed to.
✔: Generated code is up to date
Check the versions before you push
Check the event specification versions against the point where your branch started from develop. The check reads the files at that commit with git, so it needs no credentials:
snowplow-cli dp validate offline --base-ref develop
12:21PM INFO validation success data products found=1 source applications found=1
A new event specification must start at 0, and every later structural change must raise its version by one. When a version is wrong, the error names the event specification and the --fix command that writes the expected version.
The credentials are optional on your machine. If you have them, for example from snowplow-cli login, snowplow-cli dp validate --fix also checks against Console and writes the versions Console expects. Otherwise the pull request workflow runs that check for you, as described in Check and publish with GitHub Actions.
Commit the files:
git add data-structures data-products snowtype.config.json src/tracking
git commit -m "Add signup tracking"