iOS

Overview

Iteratively supports tracking analytics events from iOS apps written in Swift and Objective-C.

In Swift and Objective-C, 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.

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 folder with your Info.plist file. By default, the SDK will be generated in ./Itly/.

Tip

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

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}"
  • Select the Itly folder
  • Select Create groups
  • Make sure {Project} is checked in Add to targets
  • Click Add

Install dependencies

To validate your analytics events, the iOS 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.

pod 'Amplitude-iOS', '~> 4.5'
pod 'Mixpanel'
pod 'Analytics', '3.7.0'

Import into your app

If you are using Swift, no import is needed to use the library. If you are using Objective-C, you'll need to import it first:

#import "Itly/Itly.h"

API

Load

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

OptionsDescription
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.
isDisabled
(disabled in Objective-C)
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.
environmentSpecifies 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.
loggerTo 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 a sample logger implemented in Swift.

Optional. Defaults to standard out.
destinationsConfiguration options object to customize the analytics providers used by the Itly SDK.

Click here to see a sample custom destination implemented in Swift, and click here to see how to load a custom destination in the Itly SDK.

Required if a custom destination is connected to your iOS source.

For example:

// 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

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 View Loaded. The event was defined with one required property called name and one optional property called description. The name property's type is an enum. The description property's type is a string.

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