Using the Itly CLI
#
Setting Up ItlyItly 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 ItlyYou can install Itly from Homebrew or NPM.
- Brew
- NPM
To upgrade, run:
Install Node & NPM
We recommend installing Node via Homebrew by running brew install node
. Itly requires v8.2.0+.
#
Step 2: Initialize your project with ItlyNow that you have Itly installed, cd
into your project's root folder and initialize it with:
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 SDKNow 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.
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 productOnce you have pulled down the latest tracking plan, learn how to instrument your product.
#
Step 5: Verify the instrumentationTo 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.
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.
Utilize the Stream page to view real time events sent from your source application. See Stream resource guide.
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 Commandsitly init
#
Log into Iteratively and initialize your workspace.
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.
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:
Platform | Default location |
---|---|
Browser | ./src/itly |
Node.js | ./src/itly |
iOS | ./Itly |
Android | ./app/src/main/java/io/itly |
JRE | ./src/main/java/io/itly |
Python | ./itly |
Ruby | ./itly |
.NET | ./Itly |
To override the default location, pass the -p
argument. Itly
will remember your custom location and use it going forward.
Include -b {branch}
to generate a tracking library from a particular branch, rather than main. By default, the last published version will be used. If you'd like to generate a tracking library for another version, include -v {version}
and specify the tracking plan's version.
itly verify
#
Verify (lint) your source code for analytics.
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 -u
to update your company's tracking plan in Iteratively 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.
If you're integrating Itly into CI, there are typically two pipelines you'll want to run itly verify
in:
- Your production branch pipeline that runs when pull/merge requests get merged into your main/default branch (typically master). To make sure the code being checked there is correct and from Iteratively's main branch, run
itly verify -u -b main
. If the Iteratively branch instrumented in your source code isn't main, the command will fail; otherwise, it will update the main branch's tracking plan. - Your pull/merge request pipeline that runs when a pull/merge request is created for a branch. To verify instrumentation in this generic case, run
itly verify -u --skip-update-on-default-branch
. The command will verify against the current branch but will only update the tracking plan instrumentation status for branches other than main. This safely keeps status of events in development out of the main tracking plan.
itly verify
passes and returns an exit code of 0 if all events are tracked as expected, or fails and returns the number of events that aren't.
itly export
#
Download a tracking plan from your workspace.
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 info
#
Display information about the Itly environment.
The info
command displays information about the currently logged in
user.