Skip to main content
Data governance
Composable analytics

Manage tracking as code with Snowtype and Snowplow CLI

Keep data structures and tracking plans in your application's repository, generate tracking code with Snowtype, and check and publish every change with Snowplow CLI and GitHub Actions.

Progress0%

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:

bash
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:

yamldata-structures/com.example/signup.yaml
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:

yamldata-structures/com.example/plan.yaml
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:

yamldata-products/source-apps/web-app.yaml
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:

yamldata-products/signup-flow.yaml
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:

bash
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:

jsonsnowtype.config.json
{
"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:

bash
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:

typescript
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:

bash
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:

bash
git add data-structures data-products snowtype.config.json src/tracking
git commit -m "Add signup tracking"