Documentation

iOS SDK

Suggest Edits

Please reach out to MetaRouter before testing or implementing Analytics.js for iOS.

What is in this guide?

This guide will cover how to implement the Analytics iOS SDK for MetaRouter and begin sending events from your app into your MetaRouter cluster.

Installing the SDK

Follow the below steps to install the Analytics SDK into your app. The SDK is compatible with both Swift and Objective-C.

We recommend installing Analytics-iOS via Cocoapods as it allows you to create a build with specific destinations and makes it simple to install and upgrade.

Just add the Analytics dependency to your Podfile with:

pod 'Analytics', '~> 4.1.0'

Then, run a pod install inside your terminal, or from CocoaPods.app. Then, in your applicaton delegate's application:didFinishLaunchingWithOptions: method, set up the SDK like this:

Objective C:

SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITEKEY"];
configuration.trackApplicationLifecycleEvents = YES; // Enable this to record certain application events automatically
configuration.recordScreenViews = YES; // Enable this to record screen views automatically
configuration.requestFactory = ^(NSURL *url) {
        NSURLComponents *components = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO];
        NSString* host = components.host;
        if ([host isEqualToString:@"cdn-settings.metarouter.io"]) {
            components.host = @"YOUR_CDN_URL";
        } else if ([host isEqualToString:@"api.metarouter.io"]) {
            components.host = @"YOUR_INGESTION_URL";
        }
        NSURL *transformedURL = components.URL;
        return [NSMutableURLRequest requestWithURL:transformedURL];
    };
[SEGAnalytics setupWithConfiguration:configuration];

Swift:

let configuration = AnalyticsConfiguration.init(writeKey: "YOUR_WRITEKEY")
configuration.trackApplicationLifecycleEvents = true
configuration.recordScreenViews = true
configuration.requestFactory = { url in
    let components = NSURLComponents.init(url: url, resolvingAgainstBaseURL: false)
    if let host = components?.host {
        if host == "cdn-settings.metarouter.io" {
            components?.host = "YOUR_CDN_URL"
        } else if host == "api.metarouter.io" {
            components?.host = "YOUR_INGESTION_URL"
        }
    }
    if let transformedUrl = components?.url {
        return NSMutableURLRequest.init(url: transformedUrl)
    }
    return NSMutableURLRequest.init(url: url)
}
Analytics.setup(with: configuration)

Note: Automatically tracking lifecycle events (Application Opened, Application Installed, Application Updated) and screen views is optional via initialization config parameters, but highly recommended to hit the ground running with core events!

And of course, import the SDK in the files that you use it with:

Objective-C:

#import <metarouter/SEGAnalytics.h>

Swift:

import metarouter

Required SDK Edits

In the above SDKs, there are three places where you will need to add information custom to your MetaRouter implementation. Instructions for setting up your DNS, which includes the CDN URL and Ingestion Endpoint that you will insert into your SDK setup, can be found here. Your writeKey will indicate the specific pipeline you would like to feed your events into.

Call Methods

Identify

The identify method helps you associate your users and their actions to a unique and recognizable userID and any optional traits that you know about them. We recommend calling an identify a single time - when the user's account is first created and only again when their traits change.

Note: Users are automatically assigned an anonymousID before you identify them. The userID is then what connects anonymous activity across mobile iOS devices.

For example, a simple identify looks something like this:

Objective-C:

[[SEGAnalytics sharedAnalytics] identify:@"123456"
                                  traits:@{ @"name": @"Dagny Smith",@"email": @"[email protected]",@"role": @"buyer"  }];

Swift:

Analytics.shared().identify("123456",
    traits: ["name": "Dagny Smith","email": "[email protected]","role": "buyer"])

This call is identifying a user by her unique userID (from your database) and associating her with name, email, and role traits.

Note: When you add an identify to your iOS app, you will need to replace all those hard-coded strings with details about the currently logged-in user.

Once you have the identify call implemented, you're ready to move on to the track call.

Track

To get to a more complete event tracking analytics setup, you can add a track call to your app. This will tell MetaRouter which actions users are performing in your app. With track, each user action triggers an “event”, which can also have associated properties.

To start, our SDK can automatically track a few common events (e.g. Application_Installed, Application_Opened, and Application_Updated) - you will just need to enable this option during initialization. In addition to these, you will likely want to track some events that are success indicators for your app - like Viewed Product, Email Sign Up, Item Purchased, etc.

Setting up a track is very similar to the process you just went through to set up an identify. Here’s the basic, sample track:

Objective-C:

[[SEGAnalytics sharedAnalytics] track:@"Item Purchased",
                           properties:@{ @"item": @"Cat Feather Toy",
                                         @"revenue": @"9.99"}];

Swift:

Analytics.shared().track(
    "Item Purchased",
    properties: [
        "item": "Cat Feather Toy",
        "revenue": "9.99"
    ]
)

This example track call tells us that a user just triggered an “Item Purchased” event for an item called “Cat Feather Toy” and revenue of 9.99.

Note: In order to use a track call, you must specify a name for the event you want to track whereas properties and options are all optional fields.

A lot of analytics tools support custom event mapping so, with track implemented, you’ll be able to attribute events to your users and start targeting them in a more informed and relevant way.

Queue Flushing

You can specify the number of events that should queue before flushing. Set this to 1 to send events as they come in (i.e. not batched) but note that this will use more battery. The queue is set to 1 by default.

Objective-C:

SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"writeKey"];
configuration.flushAt = 1;
[SEGAnalytics setupWithConfiguration:configuration];

Swift:

let configuration = AnalyticsConfiguration.init(writeKey: "writeKey")
configuration.flushAt = 1
Analytics.setup(with: configuration)

Alternatively, you can flush the queue manually:

Objective-C:

[[SEGAnalytics sharedAnalytics] alias:@"marthastewart"];
[[SEGAnalytics sharedAnalytics] flush];

Swift:

Analytics.shared().alias("marthastewart")
Analytics.shared().flush()

Submitting to the App Store

When submitting to the App Store, beware that MetaRouter collects the IDFA for mobile install attribution. Even if you’re not currently utilizing mobile install attribution, if you get asked, “Does this app use the Advertising Identifier (IDFA)?” on this page, you should check the following three boxes:

  1. “Attribute this app to a previously sent advertisement”
  2. “Attribute an action taken within this app to a previously served advertisement”
  3. “I, YOUR_NAME, confirm that this app, and any third party…”

Unless you plan to display ads within your app, do not check the box labeled “Serve advertisements within the app”.

You can now use MetaRouter Analytics in your iOS app!

Migrating from Analytics 3.x to 4.x

We utilize the Segment open-source library for our iOS SDK. Recently, the SDK received an update from 3.x to 4.x that contains a significant change to middleware support, as well as a few API changes. These changes mean that a few details of the iOS SDK implementation have changed, which we will walk you through.

Upgrading the Library

Depending on how it was installed, the library can be upgraded by increasing its version inside the Podfile and running pod update, by running carthage update analytics-ios, or by just replacing the files, if it was manually copied into the project.

Updating the Imports

When using Swift, the name of the library changed from Analytics to Segment, so this means that the imports now have to be updated as well. Search inside your project for the import Analytics string and replace it with import Segment.

566

Before

584

After

The Singleton No Longer Returns an Optional

SEGAnalytics.shared() used to return an optional value in version 3.x, which means that you were required to use optional chaining. Starting with 4.x, this method no longer returns an optional value, so question marks used inside optional chaining must now be removed.

Updating the Class Names

Starting with 4.x, the main class name for the Analytics library changed from SEGAnalytics to just Analytics. This also applies for the other class names, which dropped the SEG prefix, specific to Objective-C naming conventions.

542

Before

486

After

Updating the Configuration

Aside from renaming SEGAnalyticsConfiguration to AnalyticsConfiguration, this class's initializer has also changed to better match Swift coding conventions. This means that instead of calling the init method of this class now you will directly pass the writeKey to the class constructor.

1254

Before

1242

After

Updated 8 months ago