Interacting with the SDK

Our SDKs generally involve three parts — importing, initializing, and tracking. Follow the documentation for your specific platform and language to get started.

Overview

This section describes how the auto-generated code works on the Node.js platform and the TypeScript programming language.

The SDK exposes type-safe functions for every event in your team’s tracking plan. The function’s arguments correspond to the event’s properties and are strongly-typed.

Step 1: Import

By default, Itly will generate the tracking library in ./src/itly/index.ts. The TypeScript module will automatically initialize your analytics backend SDKs (including credentials) and export a usable instance of the library. The code generated by Iteratively will import/include all SDKs for the analytics providers your team is using (e.g. Amplitude).

To use the library, import it into any module that needs to track at least one event.

import itly from './itly';

Step 2: Initialize

Initialize the Itly SDK once when your application starts. The init() method accepts an options object that lets you configure how the Itly SDK works:

OptionsDescription
contextCan be a typed object that specifies the properties to add to every event, or a resolver function that is called whenever an event is tracked and returns a just-in-time created context object.

Only available if at least one context property is defined in your tracking plan.
disabledSpecifies whether the Itly SDK does any work. When true, all calls to the Itly SDK will be no-ops. Useful in local or development environments.

Optional. Defaults to false.
environmentSpecifies the environment the Itly SDK is running in: either production or development. In production, production analytics provider Access Tokens are used and validation errors log rather than throw. In development, development analytics provider Access Tokens are used and validation errors throw exceptions.

Optional. Defaults to development.
loggerThe Itly SDK can log errors to a user-provided logger that implements debug, info, warn, and error methods.

Optional. Defaults to logging to the console.
destinationsSpecifies any analytics provider-specific configuration. The Itly SDK passes these objects in when initializing the underlying SDKs.

Required if you've configured Itly with a custom destination, or if your configured destinations require additional configuration (e.g. Android), optional otherwise.

For example:

itly.init({
context: { version: this.config.version },
disabled: process.env.APP_ENV === 'local',
environment: process.env.APP_ENV === 'production' ? 'production' : 'development',
destinations: {
segment: {
config: { flushAt: 1, flushInterval: 1 },
},
},
)},

Step 3: Track

Then, call the event’s function.

itly.trackSomeEvent({ prop: value });

Itly includes code docs in the auto-generated library so your IDE can display relevant documentation for every function and property as you type.

VS Code

Because TypeScript is a type-safe language, TypeScript itself will warn you if the arguments you pass to your track function are of the wrong type. This will not happen with type-unsafe languages (e.g. JavaScript), but in those cases, the auto-generated library will perform those checks at runtime.

SDKs

Below is SDK specific documentation or view examples to get started.

Node.js — JavaScript

See example below for Node.js — TypeScript

Node.js — TypeScript

Import

import itly from './itly';

Initialize

itly.init({
context: { /* your context properties */ },
disabled: process.env.APP_ENV === 'local', /* disable if running locally */
environment: process.env.APP_ENV === 'production' ? 'production' : 'development',
destinations: { /* optionally configure enabled destinations */
segment: {
config: { flushAt: 1, flushInterval: 1 },
},
},
});

When calling itly.init(),

Track

itly.trackUserSignedIn(userId, { platform: 'web' });

Browser — JavaScript

See example below for Browser — TypeScript

Browser — TypeScript

Import

import itly from './itly';

Initialize

itly.init({
context: { /* your context properties */ },
disabled: process.env.REACT_APP_ENV === 'local', /* disable if running locally */
environment: process.env.REACT_APP_ENV === 'production' ? 'production' : 'development',
logger: {
debug: message => console.error(message),
info: message => console.log(message),
warn: message => console.log(message),
error: message => console.error(message),
},
});

Track

itly.trackUserSignedIn({ platform: 'web' });

iOS — Swift

One-Time Setup

After calling itly pull for the first time, add the generated tracking library to your project.

  • Right click on the yellow project folder and click Add Files to "{Project-Name}"
  • Select the Itly folder
  • Select "Create groups"
  • Make sure {Project-Name} is checked in Add to targets
  • Click Add

Dependencies

To validate your analytics events, the Swift SDK depends on DSJSONSchemaValidation (MIT). To install this dependency with CocoaPods:

  • Close Xcode
  • If you haven't already, install CocoaPods with sudo gem install cocoapods
  • If you haven't already, create a file called Podfile in the project root folder (the one with your .xcodeproj) and edit it to contain:
platform :ios, '9.0'
target '{Project-Name}' do
use_frameworks!
pod 'DSJSONSchemaValidation'
end
  • If you already had a Podfile, simply add pod 'DSJSONSchemaValidation' to your target
  • Run pod install
  • Open Xcode but don't open the .xcodeproj file, instead open the .xcodeworkspace file

If you've configured Itly with Amplitude, Segment, or Mixpanel, you'll also install each configured provider's SDK:

  • Edit your Podfile and add the relevant pods. For example:
    • pod 'Amplitude-iOS', '~> 4.5'
    • pod 'Mixpanel'
    • pod 'Analytics', '3.7.0'

Initialize

// With no context properties
Itly.setup(ItlyOptions())
// With context properties (e.g. a string property called version)
Itly.setup(ItlyOptions(context: Context(version: "1.0")))

Track

Itly.instance.trackViewLoaded(ViewLoaded(name: .firstView))

iOS — Obj-C

One-Time Setup

After calling itly pull for the first time, add the generated tracking library to your project.

  • Right click on the yellow project folder and click Add Files to "{Project-Name}"
  • Select the Itly folder
  • Select "Create groups"
  • Make sure {Project-Name} is checked in Add to targets
  • Click Add

Dependencies

To validate your analytics events, the Swift SDK depends on DSJSONSchemaValidation (MIT). To install this dependency with CocoaPods:

  • Close Xcode
  • If you haven't already, install CocoaPods with sudo gem install cocoapods
  • If you haven't already, create a file called Podfile in the project root folder (the one with your .xcodeproj) and edit it to contain:
platform :ios, '9.0'
target '{Project-Name}' do
use_frameworks!
pod 'DSJSONSchemaValidation'
end
  • If you already had a Podfile, simply add pod 'DSJSONSchemaValidation' to your target
  • Run pod install
  • Open Xcode but don't open the .xcodeproj file, instead open the .xcodeworkspace file

If you've configured Itly with Amplitude, Segment, or Mixpanel, you'll also install each configured provider's SDK:

  • Edit your Podfile and add the relevant pods. For example:
    • pod 'Amplitude-iOS', '~> 4.5'
    • pod 'Mixpanel'
    • pod 'Analytics', '3.7.0'

Import

#import "Itly/Itly.h"

Initialize

// With no context properties or custom destinations
[Itly init];
// With context properties (e.g. a string property called version)
[Itly init:[ItlyOptions context:[Context version:@"1.0"]]];
// With a custom destination
ItlyCustomOptions *options = [ItlyCustomOptions adapter:[[MyCustomAdapter alloc] init]];
[Itly init:[ItlyOptions destinations:[ItlyDestinations custom:options]]];

Track

// Track a User Signed In event with a required string property called platform
[[Itly instance] trackUserSignedIn:[UserSignedIn platform:@"ios"]];
// Track a User Signed Out event with a required string property called platform
// and an optional boolean property called reset
[[Itly instance] trackUserSignedOut:[UserSignedOut
platform:@"ios"
builderBlock:^(UserSignedOutBuilder *builder) {
builder.reset = YES;
}
]];

In Objective-C, the builder pattern is used to set optional properties.

Custom Destination

If you've configured a custom destination in your tracking plan, the Itly SDK will expose an additional interface called ItlyDestination. You'll implement this interface to provide logic for each of the low-level methods the Itly SDK calls into.

A sample custom destination may look something like this. Leave any methods you will not be calling on the Itly SDK (e.g. alias()) empty.

MyCustomAdapter.h:

#include "Itly/Itly.h"
#ifndef MyCustomAdapter_h
#define MyCustomAdapter_h
@interface MyCustomAdapter: NSObject<ItlyDestination>
@end
#endif /* MyCustomAdapter_h */

MyCustomAdapter.m:

#import "MyCustomAdapter.h"
@implementation MyCustomAdapter
- (instancetype)init {
if (self = [super init]) {
NSLog(@"Itly: init");
}
return self;
}
- (void)alias:(NSString *)userId previousId:(NSString *)previousId {
NSLog(@"Itly: alias: userId: %@, previousId: %@", userId, previousId);
}
- (void)identify:(NSString *)userId properties:(NSDictionary *)properties {
NSLog(@"Itly: identify: userId: %@, properties: %@", userId, properties);
}
- (void)group:(NSString *)groupId properties:(NSDictionary *)properties {
NSLog(@"Itly: group: groupId: %@, properties: %@", groupId, properties);
}
- (void)track:(NSString *)userId eventName:(NSString *)eventName properties:(NSDictionary *)properties {
NSLog(@"Itly: track: eventName: %@, properties: %@", eventName, properties);
}
- (void)reset {
NSLog(@"Itly: reset");
}
@end

Android — Kotlin

Dependencies

To validate your analytics events, the Kotlin SDK depends on everit-org/json-schema (Apache License 2.0). To install this dependency with Gradle:

  • Edit the project-level build.gradle and add the following to allprojects.repositories (the JSON Schema validation package from Everit is published to JitPack): maven { url 'https://jitpack.io/' }
  • Edit the app-level build.gradle and add the following to dependencies:
    • implementation 'com.github.everit-org.json-schema:org.everit.json.schema:1.12.0'

If you've configured Itly with Amplitude, Segment, or Mixpanel, you'll also install each configured provider's SDK:

  • Edit the app-level build.gradle and add the following to dependencies. For example:
    • implementation 'com.amplitude:android-sdk:2.14.1'
    • implementation 'com.mixpanel.android:mixpanel-android:5.+'
    • implementation 'com.segment.analytics.android:analytics:4.+'

Import

import io.itly.*;

Initialize

Itly.instance.init(
ItlyOptions(
Context(version = "1.0"),
ItlyDestinations(ItlyAmplitudeOptions(applicationContext))
)
);

Track

Itly.instance.trackActivityCreated(
ActivityCreated(title = ActivityCreated.Title.MAINACTIVITY)
)

Android — Java

Import

import io.itly.*;

Initialize

Itly.getInstance().init(ItlyOptions.builder()
.destinations(ItlyDestinations.builder()
.amplitude(new ItlyAmplitudeOptions(getApplicationContext()))
.build())
.context(Context.builder()
.version("1.0")
.build())
.logger(new Logger())
.disabled(false)
.environment(ItlyOptions.Environment.DEVELOPMENT)
.build());

Track

Itly.getInstance().trackActivityCreated(ActivityCreated.builder()
.title(ActivityCreated.Title.MAINACTIVITY)
.build());