Android (3.0)

Overview

Iteratively supports tracking analytics events from Android apps (API 22 and above) written in Kotlin and Java.

In Kotlin and Java, the tracking library exposes a type-safe function for every event in your team’s tracking plan. The function’s arguments correspond to the event’s properties and are strongly typed to allow for code completion and compile-time checks.

About Android (3.0)

The Android (3.0) SDK enjoys a simpler deployment model and introduces several new features to help developers implement product analytics:

  • Previously, the entire SDK was codegen'd into your source tree. In 3.0, the SDK is split into two, allowing developers to call itly pull freely without worrying about pulling down changes that may affect their application's behavior:
    • The static, core SDK — open source and hosted on GitHub, and usable standalone, it contains all the logic needed to validate, track, and test analytics events. It is now semantically versioned and published to popular package repos, incl. Maven Central.
    • The dynamic, codegen'd API — generated by itly pull and placed into your source tree, the codegen'd API contains event classes and a corresponding strongly-typed API only. It delegates all work to the core SDK and contains no logic.
  • The core SDK is now extensible via plugins. 5 plugins are currently available out of the box: a JSON Schema validation plugin, and 4 destination plugins: Segment, Amplitude, Mixpanel, and Iteratively.
  • When environment is set to development, the SDK will stream events to Iteratively's new Stream dashboard. The live debugger allows developers to watch tracked events, inspect their payloads, and detect validation problems.

Installation

Generate the SDK

If you have not yet installed the Itly CLI, install it now.

To generate the Itly SDK, run itly init and itly pull {source} in the top-most folder of your project. By default, the SDK will be generated in ./app/src/main/java/ly/iterative/itly/.

Tip

{source} is the name of the source you created in your tracking plan (e.g. android).

Install dependencies

Edit the app-level build.gradle and add the following to dependencies:

  • implementation 'ly.iterative.itly:sdk-android:1.2.0'
  • implementation 'ly.iterative.itly:plugin-iteratively:1.2.0'
  • implementation 'ly.iterative.itly:plugin-schema-validator:1.2.0'

For Amplitude:

  • implementation 'ly.iterative.itly:plugin-amplitude-android:1.2.0'

For Mixpanel:

  • implementation 'ly.iterative.itly:plugin-mixpanel-android:1.2.0'

For Segment:

  • implementation 'ly.iterative.itly:plugin-segment-android:1.2.0'

Note: if you're not already requesting the INTERNET permission, add <uses-permission android:name="android.permission.INTERNET" /> to your AndroidManifest.xml.

Import into your app

To use the library, you'll need to import it first:

import ly.iterative.itly.*

API

Load

Load the Itly SDK once when your application starts. The load() method accepts a few configuration option arguments:

Itly.load(
Context(version = "1.0"),
DestinationsOptions(
AmplitudeOptions(applicationContext),
MixpanelOptions(applicationContext),
SegmentOptions(applicationContext)
),
Options(
plugins = listOf(MyCustomDestination())
)
);

In our example above, we defined a tracking plan in the Itly web application to:

  • Include a property called version on every event
  • Send events to Amplitude, Mixpanel, Segment, and a custom destination

As a result, our SDK will be initialized to:

  • Set the required version property to 1.0
  • Send events to a custom destination implemented in the MyCustomDestination class


ArgDescription
contextAn object with a set of properties to add to every event sent by the Itly SDK.

Only available if there is at least one source template associated with your your team's tracking plan.
destinationsSpecifies any analytics provider-specific configuration. The Itly SDK passes these objects in when loading the underlying analytics provider libraries.

Optional.
optionsSpecifies additional configuration options for the Itly SDK. Optional.

disabled
Specifies 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.

environment
Specifies the environment the Itly SDK is running in: either production or development. Environment determines which Access Token is used to load the underlying analytics provider libraries.

The option also determines safe defaults for handling event validation errors. In production, when the SDK detects an invalid event, it will log an error but still let the event through. In development, the SDK will throw an exception to alert you that something is wrong.

Optional. Defaults to development.

plugins
An array of additional plugins to load into the Itly SDK. Plugins allow you to extend the Itly SDK's event validation and event tracking functionality with your own. For example, a plugin can be used to implement a custom destination or a custom event validator.

Click here to learn about writing a custom destination plugin.

Click here to see a sample custom destination plugin.

logger
To log Itly's logs to a custom logger, implement the ItlyLogger protocol and set logger to an instance of your class. The Itly SDK will call into your class with all debug, info, warn, and error-level messages.

Click here to see an example written in Kotlin.

Click here to see an example written in Java.

Optional. Defaults to standard out.
Note

The Itly SDK will automatically load and initialize your analytics providers' libraries using your each library's official installation instructions.

Track

To track an event, call the event’s corresponding function. Every event in your tracking plan gets its own function in the Itly SDK.

For example, in the code snippet below, our tracking plan contains an event called Activity Created. The event was defined with one required property called title. The property's type is an enum.

Itly.activityCreated(
title = ActivityCreated.Title.MAIN_ACTIVITY
)

Example

Browse over to https://bitbucket.org/seasyd/examples/src/master/android-kotlin-v3/ to see an example of an instrumented Kotlin app, along with a sample implementation of the MyCustomDestination plugin.