Using the Itly CLI (w/ branches)

Setting Up Itly

Itly is Iteratively’s command line app. It works hand-in-hand with the Iteratively web app and enables developers to quickly and correctly instrument tracking code in their apps.

Step 1: Install Itly

You can install Itly from Homebrew or NPM.

brew install iterativelyhq/itly/itly

To upgrade, run:

brew update && brew upgrade itly

Step 2: Initialize your project with Itly

Now that you have Itly installed, cd into your project's root folder and initialize it with:

itly init

A browser window will open and automatically log you in or prompt you for your credentials. Itly will store your project-specific settings in .itlyrc and your user-specific settings (such as your credentials) in ~/.itlyrc.

Step 3: Generate your analytics SDK

Now that you're done setting Itly up, you’re ready to generate your analytics SDK. The itly pull command looks at the events and properties you've defined in your Iteratively account (this is also commonly referred to as a tracking plan) and auto-generates a matching type-safe analytics library for you to use.

itly pull {source-name}

The pull command takes one argument: the name of a source created in your Iteratively account. For example, a source might be ios, android, web, or backend. Events associated with a particular source will appear in the auto-generated SDK. Those that aren't will not. This makes sure your events are tracked consistently on all the sources you'd like to track them on.

The pull command will also tell you what, if anything, has changed since the last time you pulled your team's analytics spec. You can use this as a guide for getting your analytics instrumentation up-to-date.

As your project progresses, you and your team will inevitably make changes to your tracking plan. Iteratively will notify you when those changes are made and when you’re ready, you can pull down the changes and incorporate them into your project.

Step 4: Instrument your product

Once you have pulled down the latest tracking plan, learn how to instrument your product.

Browser - JavaScript
Node.js - TypeScript
Android - Kotlin
.NET — C#

Step 5: Verify the instrumentation

To make sure you’re tracking all the right events, and that you’re tracking those events correctly, Itly can lint your source code and warn you about any errors. For example, Itly can tell if you’ve forgotten to track any required events, or if you’re not passing along all required properties.

itly verify

The verify command will scan your source code for tracking calls and compare the results to what's expected per your team's tracking plan. Include --update to update your company's tracking plan online and share the latest analytics implementation status with your team. If the command reports all green, you're all good!

You can configure your CI pipeline to automatically run the verify command at check-in so you never miss another analytics bug again.

Tracking Status

Iteratively can generate reports that can summarize the status of your analytics instrumentation. The reports serve as a one-stop-shop for understanding progress made, adherence to the tracking plan, and issues that will cause analytics data reliability or consistency problems downstream.

  • A red cross indicates the event is not yet instrumented for a given Source.
  • A green checkmark indicates the event has been instrumented for a given Source.

Hovering over the checkmark shows the exact location or locations in the source code the event is currently instrumented in.

Itly CLI Commands

itly init

Log into Iteratively and initialize your workspace.

$ itly init

The init command logs you into your Iteratively account. It's the first command you'll run after installing Itly on your computer. You only need to run the command once.

itly pull

Pull down the latest tracking plan and generate a tracking library.

$ itly pull <source>
$ itly pull web

Run this command in the root folder of your project. For example:

  • Browser & Node.js: the folder with your package.json
  • iOS: the folder with your Info.plist
  • Android: the folder with your {project-name}.iml

By default, your tracking library will be placed in:

PlatformDefault location

To override the default location, pass the --path argument. Itly will remember your custom location and use it going forward.

itly pull web --path ./src/analytics

To generate a tracking library from a branch other than master, pass the --branch (or -b) argument. Itly will remember the most recently used branch and use it going forward.

itly pull web -b develop

itly verify

Verify (lint) your source code for analytics.

$ itly verify
-u, --update=update update the tracking status online
-t, --token=token personal API token to authenticate with
$ itly verify
$ itly verify -u -t $ITLY_KEY

Run this command in the root folder of your project. The command will scan your source files, locate all calls to the Itly tracking library, and let you know which events are being tracked, and which have yet to be instrumented.

Include --update to update your company's tracking plan online and share the latest analytics implementation status with your team. Your teammates will be able to tell when events were first implemented, the last time they've been detected in the source code, and where exactly in the source code they are tracked.

itly export

Download a tracking plan from your workspace.

$ itly export [<source>] [-f <path>] [-t <token>]
-f, --file=file [default: schema.json] file path to export to
-t, --token=token personal API token to authenticate with
$ itly export ios
$ itly export -f schema.json

The export command exports your team's tracking plan into a JSON file (schema.json by default). Your team's event, context, identify, group, and page schemas will be included. Each item's schema is represented in the JSON Schema format.

itly help

Display help for Itly.

$ itly help [command]

itly info

Display information about the Itly environment.

$ itly info

The info command displays information about the currently logged in user.

Branches & Best Practices

In addition to being versioned, Iteratively tracking plans can also be branched. This feature lets you work on changes to your tracking plan in a separate area, and allows for reviews and approvals before the changes are merged back into the main, official branch.

Branch Limits

Iteratively currently only supports up to 2 branches: the main, official branch, and one other branch.

Let's consider a typical workflow for a team using the main, official branch for a production-ready tracking plan and the second branch for a work-in-progress tracking plan. This team would likely have:

  • In Git, a branch called master and feature-x
  • In Iteratively, a branch called master and develop

Let's say your team has just started working on Feature X and decided to track some analytics. You would:

  1. Open Iteratively and create new events in the develop branch. You're likely to iterate on these, so don't worry about getting them perfect.
  2. Back in your terminal, run itly pull -b develop. When working out of a branch, you don't need to publish a new tracking plan for every change! Itly will grab the latest changes automatically to speed up your workflow.
  3. Instrument your new events and run itly verify -u to keep your team in sync on what's implemented and what's pending.
  4. When you're all done and happy with your new tracking plan, it's time to get it reviewed and approved. Create a new Merge Request in Iteratively and ask your team's approvers to take a look.
  5. Make any requested changes in the Iteratively develop branch and once all required approvers have signed off, make it official and merge the new tracking plan into master.
  6. You're now ready to wrap up instrumenting feature-x. Run itly pull -b master (this should produce no changes) and commit. Your feature-x branch is now ready to merge into master in Git!
Conflicts in .itlyrc

Did a merge or rebase in Git create a conflict in .itlyrc? If that happens, delete .itlyrc, and run itly init and itly pull -b master.