SDK Reference

iOS SDK

This manual provides detailed technical instructions for installing the Umbel iOS SDK.

You will need the following from your Umbel Client Success Engineer to complete implementation:

  1. Download the Umbel iOS SDK
  2. Umbel-provided API Key
  3. Umbel-provided starter tags
  4. Login to your Umbel account

Umbel’s implementation for an iOS supported mobile app requires the installation of Umbel’s iOS SDK on the areas of your app that you wish to report on.

The Umbel SDK for iOS is used to pass data directly and securely from an iOS device to Umbel’s collection infrastructure.

Please note:

Step 1: Implementation

  1. Open your iOS project in Xcode
  2. Drag UmbelSDK.h and libUmbelSDK.a from the Umbel_SDK directory into your project
  3. Include the CFNetwork, and SystemConfiguration frameworks in your project
  4. Link against libsqlite3.dylib framework
  5. Facebook SDK version 3.7 or higher
  6. Include the Social.framework, Accounts.framework, Security.framework with the Optional flag
  7. In the project settings Other Linker Flags and -ObjC

Step 2: Initialization

  1. In your AppDelegate didFinishLaunchingWithOptions function, add the following code to initialize the Umbel SDK:
#import "UmbelSDK.h"
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
…
 [UmbelSDK setup:@"xxxxxxxx" propertyName:@"<property_name>" enableFederated:NO enableTesting:NO];
…
 return YES;
}

Step 3: Send Events to Umbel

Once the SDK has been added, Umbel will start to receive basic device data about your app’s users. Additional calls to the API can be made to set segments and track other events via tags.

Commands

Example:

[UmbelSDK setSampleRate:1];

To deliver a user’s email address to Umbel, run the following setEvent command:

[UmbelSDK setEvent:@"profile.email" eventValue:@"example@umbel.com"];

For iOS 6 and above you can also setEvent the advertiser ID:

[UmbelSDK setEvent:@"profile.ios_advertiser_id" eventValue:@"1CB75145-2B41-4ABD-9693-92BC25E5456"];

Tagging: Segments

The tag event type is used to define segments within your audience based on tags that you create. These custom tags allow Umbel to report on user interactions (i.e. clicks, downloads, form submissions, video plays, etc.) across your app. Tags are used to append extra metadata to a user’s profile, which is later used to segment and filter your audience.

Note that this tag function takes a variable argument list of NSStrings that must be nil terminated.

[UmbelSDK tag:@"rate_app", nil];

Tagging: Tag Hierarchy

Tag names can be structured to represent and organize the engagement behaviors from your app. You will likely need to track other engagement metrics specific to your property, and the Umbel tag allows for the creation of unique structured segments. For example a game app may wish to measure the user engagement level by progress in the game. These following two tags could track those events.

[UmbelSDK tag:@"Levels", @"level_1", nil];

Umbel will help your team to evaluate your app and design a tagging strategy to capture the goals and conversion events that will yield valuable user segments.

[UmbelSDK tag:@"Bands", @"U2", nil];
[UmbelSDK tag:@"Tickets", @"VIP", nil];

Alternatively you can use the tagArray function to pass these arguments in as an array instead of a variable argument list.

[UmbelSDK tagArray:NSArray];

When your app sends data directly through the iOS SDK, it is ultimately organized in Umbel’s systems, creating metrics and statistical overlays. The table below contains the list of accepted events for the Umbel SDK.

Additional Event Types:

Event Tag Name What the Event Does Example Values
action.tag Used for segmenting session data per profile [“homepage”] or [“sports”, ‘’NFL”]
profile.unique_id (optional) cross domains support A unique string per user
profile.zip (optional) to segment data geographically 78701
profile.city (optional) metadata per user Austin
profile.country (optional) metadata per user US
profile.state (optional) metadata per user TX
profile.birth_year (optional) metadata per user 2011
profile.gender (optional) metadata per user M or F
profile.email (optional) if different from Facebook test@umbel.com
profile.facebook_access_token Used to gather social data AAADSxG9Y4yABAJzqAQuCmBZ…
profile.twitter_user_id Used to gather social data 42668969

Step 4: Facebook Integration

If your iOS app provides Facebook login then Umbel can accept that authentication token to append the user’s social graph to their Umbel profile. Send Facebook Tokens to Umbel with the following event.

[UmbelSDK setEvent:@"profile.facebook_access_token" eventValue:@"AAADSxG9Y4yABAJzqAQuCmBZ..."];

Further Reference from Facebook:

Step 5: Federated Property Support

For clients with federated properties only.

Federated accounts allow user profiles to be shared across multiple properties. If you have a federated Umbel property, then the Umbel iOS SDK will allow you to attribute events to any property in your approved list. First, the Umbel SDK must be setup in federated mode with enableFederated:YES in the initial setup function. To switch to a different property, use the setFederatedProperty function:

[UmbelSDK setup:@"xxxxxxxx" propertyName:@"<property_name>" enableFederated:YES enableTesting:NO];
 [UmbelSDK setFederatedProperty:@"<property_name>"];

Step 6: Staging, QA, & Launch

Staging

Once you’ve begun staging and testing this SDK integration with your mobile app, Umbel needs to verify that events are being captured correctly and perform a final code review before you are able to deploy Umbel to your production site. Please contact your Client Services Director and/or Client Success Engineer once you are ready to start testing. If you do not have their contact information, please notify the following email distribution lists and your Umbel team will contact you promptly:

Launch

After it has been confirmed that we’ve received your data, your Client Services Director will:

Android SDK

This manual provides detailed technical instructions for installing the native Android SDK.

You will need the following from your Umbel Client Success Engineer to complete implementation:

Umbel’s implementation for an Android supported mobile app requires the installation of Umbel’s Android SDK to the areas on your app on which you wish to report.

The Android version of the Umbel SDK is used to pass data directly and securely from an Android device to Umbel’s collection infrastructure.

Please note:

The SDK automatically collects device information and adds this to the user’s profile.

Step 1: Install Umbel’s SDK

  1. Drop the mobile-sdk-android.jar on the libs folder on your android project
  2. AndroidManifest.xml:
  3. Add the following inside the Application: <service android:name="com.umbel.CloudService"></service> <receiver android:name="com.umbel.AlarmReceiver"></receiver>
  4. Add the following permissions outside the application tag: <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Step 2: Initialization

In your primary activity’s onCreate method, add the following code to initialize the Umbel SDK:

import com.umbel.UmbelSDK;
UmbelSDK.setup("xxxxxxxx", this);

Replace xxxxxxxx with the API key assigned to your account

Step 3: Send Events to Umbel

Once the SDK has been added, Umbel will start to receive basic device data about your app’s users. Additional calls to the API can be made to set segments and track other events via tags.

Commands:

setEvent: the Set command will store a local copy of the event value and then only send the value to Umbel when the data changes.

tag: the Tag command sends an action.tag event which is used the segment your audience.

purchaseEvent: the purchase command can track all in-app-purchases associated with this user’s profile.

dispatch: send the current queue of events manually instead of waiting for the queue to reach the sample rate amount. Events sent into the Umbel SDK are queued and sent in batches of two by default.

You can override this value through setSampleRate:

UmbelSDK.setSampleRate(2);

Tagging: Segments

The tag event type is used to define segments within your audience based on tags you create that allow Umbel to report on user interactions (i.e. clicks, downloads, form submissions, video plays, etc.) across your app. Tags are used to append extra metadata to a user’s profile, which is later used to segment and filter your audience.

Note that this tag function takes a variable argument list of NSStrings that must be nil terminated.

UmbelSDK.tag(new String[]{"rate_app"});

Tagging: Tag Hierarchy

Tag names can be structured to represent any type of data organization you choose. You can use any number of levels depending on how you would like to segment and filter the tags. To help you get started, the Umbel team will send you three to five suggested starter tags:

Example Tagging Hierarchy:

Tag with a three-level hierarchy:

UmbelSDK.tag(new String[]{"Sports","NFL","Jets"});

Or simply tag a single category:

UmbelSDK.tag(new String[]{"completed_level_1"});

Or you could create a hierarchy that is only two levels deep:

UmbelSDK.tag(new String[]{"ad_clicktru","tapjoy"});

When your app sends data directly through the SDK it is ultimately organized in Umbel’s systems, creating metrics and statistical overlays. While the Umbel SDK will accept any event name, below is the whitelist of events that are calculated into the analytics dashboard.

Example Tags:

Event Tag Name What the Event Does Example Values
action.tag Used for segmenting session data per profile [“homepage”] or [“sports”, ‘’NFL”]
profile.unique_id (optional) cross domains support A unique string per user
profile.zip (optional) to segment data geographically 78701
profile.city (optional) metadata per user Austin
profile.country (optional) metadata per user US
profile.state (optional) metadata per user TX
profile.birth_year (optional) metadata per user 2011
profile.gender (optional) metadata per user M or F
profile.email (optional) if different from Facebook test@umbel.com
profile.facebook_access_token Used to gather social data AAADSxG9Y4yABAJzqAQuCmBZ…
profile.twitter_user_id Used to gather social data 42668969

Step 4: Facebook Integration

If your iOS app provides a Facebook login, then Umbel can accept that authentication token and append the user’s social graph to the Umbel profile.

Send Facebook Tokens to Umbel with the following event.

UmbelSDK.setEvent("profile.facebook_access_token", "AAADSxG9Y4yABAJzqAQuCmBZ...");

Further Reference from Facebook:

Step 5: Staging, QA, & Launch

Staging

Once you’ve begun staging and testing this SDK integration with your mobile app, Umbel needs to verify that events are being captured correctly and perform a final code review before you are able to deploy Umbel to your production site.

Please contact your Client Services Director and/or Client Success Engineer once you are ready to start testing. If you do not have their contact information, please notify the following email distribution lists and your Umbel team will contact you promptly:

Launch

After it has been confirmed that we’ve received your data, your Client Services Director will:

JavaScript

This manual provides detailed technical instructions for installing the Javascript SDK on your website.

You will need the following from your Umbel Client Success Engineer to complete implementation:

Umbel integration for websites requires the placement of JavaScript on the areas of your website where you want to gather reporting and insights. This allows you to gather metrics throughout your site with little performance impact.

Step 1: Place Umbel’s JavaScript SDK on your Site

Umbel’s JavaScript is used to pass data directly and securely from a web browser to Umbel’s collection infrastructure. Placing Umbel’s JavaScript on your site automatically assigns a unique ID that is associated with the user’s profile. This ID is a UUID stored in a cookie called umbel_browser_id. To avoid cross-domain security issues and maximize browser compatibility, we use the single-pixel GIF request method to pass this information in the URL parameters via an HTTP GET request.

The minimum requirements for Umbel’s JavaScript include the following browsers with cookie, SSL and JavaScript support enabled:

Your Umbel Client Success Engineer or Client Services Director will email you your API key, property ID, and a text file containing Umbel Javascript to be placed on your site. If you have not received this key, please contact us at support@umbel.com.

Place the below JavaScript before the closing tag on your site. XXXXX represents the API key assigned to your property. YYYY represents your property ID.

SDK Web Initialization

<script>
  window._umbel = window._umbel || [];
  (function() {
    var u = document.createElement("script")
    u.async = true;
    u.src = "https://static.umbel.com/sdk/1.0.0.js?d=" + new Date().getMonth() + '-' + new Date().getDate();
    u.onload = function () {
      new Umbel({
        apiKey: "XXXXX",
        propertyId: YYYY
      })
    };
    document.head.appendChild(u);
  })();
</script>

React Native Intialization

var Umbel = require("./path/to/umbel-sdk.js")
// global._umbel is available after import to start using .push() for sending events

var umbel = new Umbel({
  apiKey: "XXXXX",
  propertyId: YYYY,
})

Umbel initialization arguments

Argument Type Required Description Default value
apiKey String true Umbel API key provided by your client partner (None)
propertyId Number true Umbel Property ID provided by client partner (None)
onInit Function false Callback that is called after SDK initializes (None)
urlParamsToSend String[] false Query string params to send to Umbel []
testMode Boolean false Flag for testing SDK during setup false
krux Boolean false Flag to collect Krux ID false
gigya Boolean false Flag to collect Gigya ID false
collectFBSdkToken Boolean false Flag to collect FB SDK Token false
collectFBReferrerCode Boolean false Flag to collect FB Referrer Code false
collectFBClientToken Boolean false Flag to collect FB Client Token false

Legacy SDK Web Initialization

<script type="text/javascript">
 window._umbel = window._umbel || [];
 (function() {
        var u = document.createElement('script'); u.type = 'text/javascript'; u.async = true;
        u.src = document.location.protocol + '//tags.api.umbel.com/XXXXX/w.js?d=' + new   Date().getMonth() + '-' + new Date().getDate();
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(u, s);
 })();
</script>

Step 2: Send Events to Umbel

Once the JavaScript code has been added, Umbel will start to receive data about your site’s users. Additional calls to the API can be made to set segments and track other events via tags.

It is important to note the following throughout the Umbel installation:

The Umbel JavaScript API call contains 3 components

_umbel.push({[command], [name], [value]});
command - how to send and cache the event
name    - event name
value   - event value

We employ two types of commands in the API call: “set” and “send.”

The “set” command will store a local copy of the event value in a cookie and only send a unique value pair once to Umbel. “set” only sends changes to the event’s value.

HINT: To deliver a user’s email address to Umbel, run the following “set” command:

_umbel.push({"type": "set", "name": "profile.email", "value": "example@umbel.com"});

The “send” command sends every event, regardless of uniqueness.

HINT: To re-send data (for tracking session or user activity), run the “send” command:

_umbel.push({"type": "send", "name": "action.tag", "value": ["sports"]});

Tagging Segments

The "action.tag" event type is used to define segments within your audience based on tags you create that allow Umbel to report on user interactions (i.e. clicks, downloads, form submissions, video plays, etc.) across your site. Tags are used to append extra metadata to a user’s profile, which is later used to segment and filter your audience.

Tagging: Tag Hierarchy

Tag names can be structured to represent and organize the engagement behaviors from your site. To deliver the best actionable results we recommend the following tagging strategy for the core engagement metrics. Each of these tags can be sent with a JavaScript event like this:

_umbel.push({"type": "send", "name": "action.tag", "value": ["Sharing", "Twitter"]});

You will likely need to track other engagement metrics specific to your property, and the action.tag allows for the creation of unique structured segments. For example a concert ticketing site may wish to measure tickets sold and band engagement level. These following two tags could track those events.

_umbel.push({"type": "send", "name": "action.tag", "value": ["Bands", "U2"]});
_umbel.push({"type": "send", "name": "action.tag", "value": ["Tickets", "VIP"]]});

Supported Events:

Event Tag Name What the Event Does Example Values
action.tag Used for segmenting session data per profile [“homepage”] or [“sports”, ‘’NFL”]
profile.unique_id (optional) cross domains support A unique string per user
profile.zip (optional) to segment data geographically 78701
profile.address (optional) Send address data (Each field is optional.You can send all values or one) {“street”: “123main”, “street2”: “suite111”, “city”: “Austin”, “state”: “TX”, “postal_code”:“78701”, “country”: “US” }
profile.birth_year (optional) metadata per user 2011
profile.gender (optional) metadata per user M or F
profile.email (optional) if different from Facebook test@umbel.com
profile.facebook_access_token Used to gather social data AAADSxG9Y4yABAJzqAQuCmBZ…
profile.twitter_user_id Used to gather social data 42668969


Example Tags

_umbel.push({"type": "set", "name": "profile.zip", "value": "78701"});
_umbel.push({"type": "set", "name": "profile.birth_year", "value": "2011"});
_umbel.push({"type": "set", "name": "profile.gender", "value": "M"});
_umbel.push({"type": "set", "name": "profile.facebook_access_token", "value": "AAADSxG9Y4yABAJzqAQuCmBZ..."});
_umbel.push({"type": "set", "name": "profile.address", "value": {"street": "123main", "street2": "suite111", "city": "Austin", "state": "TX", "postal_code":"78701", "country": "US" }});

Crossdomain Support

Umbel’s JavaScript SDK uses a common key to track a user’s actions throughout your site, but this key as a cookie is tied to one domain. If you have multiple domains and share the user’s session across them, Umbel will need a common key to make this association. We have provided a key called profile.unique that will need to be set at least once in each domain with your common user identifier (in whatever format you choose).

Below is an example using a UUID:

umbel.push({"type": "set", "name": "profile.unique_id", "value": "fffe83f7-e59e-3e9b-8ef4-0e22b4235ac1"});

Staging, QA, & Launch

Staging

Umbel needs to verify that events are being captured correctly and perform a final code review before you are able to deploy. During this time set the testing flag to true. This will tell our servers to process the data so we can verify it, but not record it.

window._umbel_test_mode = true;

Please contact your Client Services Director and/or Client Success Engineer once you are ready to start testing. If you do not have their contact information, please notify the following email distribution lists and your Umbel team will contact you promptly: support@umbel.com services@umbel.com

Launch

After it has been confirmed that we’ve received your data, your Client Services Director will:

Verify the health user registration events. Verify segments throughout the site and perform a site audit. Schedule a call with your team to perform an Umbel walk-through.