Skip to main content

Working with the Snowtype CLI

Snowtype CLI​

The Snowtype CLI is a tool which aims to speed up tracking implementations, provide type safety and inline documentation for developers and ultimately reduce the number of erroneous events. By integrating this tool in the development workflow we introduce a way to connect the additions and updates done in a Snowplow implementation with the corresponding tracking code of the project.

Authenticating with the Console​

A Console API key is required for the Snowtype CLI to authenticate with your account. You can find your own or create one in the Console API key management.

From there, the ways for the CLI to recognize the key are either through the global -k, --apiKey option or the SNOWPLOW_CONSOLE_API_KEY environment variable. The Snowtype CLI does automatically read from a .env file at the root of your project as well.

SNOWPLOW_CONSOLE_API_KEY=MY-API-KEY

Recommended: We recommend that you use the SNOWPLOW_CONSOLE_API_KEY environment variable.

Initializing Snowtype for your project​

For the Snowtype CLI to work properly, it requires a configuration file to be initialized and present on your project's root folder. This file will be automatically generated using the snowtype init command, after adding the required input.

# Start prompting for configuration inputs
npx snowtype init

The input required for the initialization to work, it the following:

  • The organization ID from the BDP console.
  • The tracker you wish to generate code for.
  • If applicable, the language for that tracker.
  • The output path you wish the CLI to generate the code to.

These will all be prompted to you by default, but if needed you can call the snowtype init command with any or all the attributes passed as optional flags so prompting is not required.

Generate tracking code​

The CLI will generate tracking code using a valid Snowtype configuration file with the snowtype generate command. The code that will be generated, depending on the language, will have all the required types used in schemas and Event Specifications together with methods/classes that allows for tracking these.

# Code will be generated to the outpath configuration
npx snowtype generate

The code generated by the CLI is not minified and contains inline documentation for methods, classes and types. If needed you can modify it in any way it suits your project.

Contents​

The contents of a generated file from the Snowtype CLI will be:

  • Types/Interfaces/Classes for each schema that relates to the Data Structures, Iglu Central Schemas and Event Specifications selected.
  • For each schema:
    • A method/class to instantiate the structure as a Self Describing JSON. This is particularly useful to add entities as extra context on events.
    • A method that sends a Self Describing Event with the schema as the main event entity.
  • For each Event Specification, a method/class to track the specific event specification.
caution

The Snowtype CLI does not automatically install the required Snowplow tracking libraries. For now it generates code that use the tracking libraries which are expected to be installed on the project.

Available Trackers/Languages​

Following is the set of available trackers and languages the Snowtype CLI currently can work with. This list is also the source of truth for valid keys in the tracker and language attributes of the Snowtype configuration file.

TrackerLanguage/s
@snowplow/browser-trackerjavascript, typescript
@snowplow/node-trackerjavascript, typescript
@snowplow/react-native-trackertypescript
@snowplow/javascript-trackerjavascript
snowplow-golang-trackergo
snowplow-ios-trackerswift
snowplow-android-trackerkotlin

Example Usage​

Below we show example usage of the generated code. For demonstration, we assume the code was generated for the web_page and product schemas.

import {
  trackWebPage,
  createProduct,
  WebPage,
  Product,
  createWebPage,
} from "./{outpath}/snowplow";
/* Track a WebPage event */
trackWebPage({ id: "212a9b63-1af7-4e96-9f35-e2fca110ff43" });
/* Track a WebPage event with a Product context entity */
const product = createProduct({
  id: "Product id",
  name: "Snowplow product",
  currency: "EUR",
  price: 10,
  category: "Snowplow/Shoes",
});
trackWebPage({
  id: "212a9b63-1af7-4e96-9f35-e2fca110ff43",
  context: [product],
});
/* You can enforce specific context entities on any `track` function using type arguments */
const webPage = createWebPage({ id: "212a9b63-1af7-4e96-9f35-e2fca110ff43" });
trackWebPage<Product | WebPage>({
  id: "212a9b63-1af7-4e96-9f35-e2fca110ff43",
  context: [product, webPage],
});

Event Specifications​

To add an Event Specification to the code generation, either manually or through the snowtype patch command, you would need the ID of the event specification. You can find the Event Specification ID in the main page of the event specification as shown below:

event specification id

Then you should add this ID to your snowtype.config.json eventSpecificationIds array.

Data Structures​

To add a Data Structure to the code generation, either manually or through the snowtype patch command, you would need the Data Structure Schema tracking URL. You can find the Data Structure tracking URL on the Data Structure page in the Console, under the Overview tab as shown below:

data structure url

Then you should add this Data Structure tracking URL to your snowtype.config.json dataStructures array.

Iglu Central Schemas​

To add a Data Structure to the code generation, either manually or through the snowtype patch command, you would need the Schema tracking URL. You can find the Schema tracking URL on Iglu Central by searching for the schema and under the General Information tab you can find the URL as shown below:

iglu central tracking url

Then you should add this Schema tracking URL to your snowtype.config.json igluCentralSchemas array.

Generating event specification instructions​

When generating code for Event Specifications, you have the option of delivering the implementation instructions and triggers for each scenario right on the developer's environment.

By using the --instructions option on the snowtype generate command, you can generate a markdown file with all the required information about tracking an event specification.

This includes:

  • Trigger description.
  • Images uploaded on your Event Specification triggers.
  • App identifiers and URLs this event should be triggered on.
  • Direct links to the code for this Event Specification.

Keeping up with latest updates​

It is important that the tracking code is up-to-date with latest versions of Data Structures and Event Specifications we are tracking on a project. The Snowtype CLI gives the engineers the ability to check if there are available updates for Data Structures and Event Specifications that are used in the project.

This works with the snowtype update command.

npx snowtype update

The above command will output a diff showing the available version updates, similar to what you can see below:

patch command version diff

In that case, you can select to update to latest versions and regenerate the tracking code. To automatically update and regenerate the tracking code reflecting the latest updates, you can use the --yes flag.

Was this page helpful?