Close

iOS SDK

Omniata’s iOS SDK is implemented using Objective-C. By default the SDK does not log anything, i.e. uses SMT_LOG_NONE log level. The method setLogLevel of iOmniataAPI can be used to adjust the log level. When developing and testing a more verbose log level might be useful.

Please note that the SDK uses NSMutableURLRequest class for the Channel API & Event API communication. The class is rather limited as it doesn’t allow setting connection timeouts or request timeouts.

Content:

Installation and Upgrade

The latest available SDK can be found below.

Platform Links Version Release Date
iOS Source code
API details
2.2.7 7 Nov 2016

To install, add the following frameworks to your project by clicking on your Target, choosing the “Build Phases” tab and using the + button at the bottom of the “Linked Libraries” section.

  1. Foundation
  2. UIKit
  3. SystemConfiguration
  4. AdSupport

Copy the iOmniataAPI.framework to any directory in your app folder. Drag it to your Xcode project.

Integrating Omniata iOS SDK

Initialization

Include this header when using iOmnitaAPI:

#import <iOmniataAPI/iOmniataAPI.h>

To initialize you can use the following:

NSString * api_key = @"<API_KEY>";
NSString * user_id = @"<USER_ID>";
NSString * org = @"<ORG_NAME>";
[iOmniataAPI initializeWithApiKey:api_key api_key: UserId:user_id OrgName:org]; // Tracks against production API

Initialization methods can be safely called multiple times or from multiple threads simultaneously, however only the first call initializes. The subsequent calls are ignored.

The value in <ORG_NAME> is the organization part of the URL you use to access Omniata Panel, for example in https://acme.panel.omniata.com the <ORG_NAME> value would be “acme”. The same principle applies to <USER_ID> which is your in-app user identifier and <API_KEY> which is the qualifier for the application and environment of the current build.

You can also initialize with customized base API endpoint, for this your event API should be <baseURL>/event? and your channel API should be <baseURL>/channel?. Then in your code use the following:

NSString * api_key = @"<API_KEY>";
NSString * user_id = @"<USER_ID>";
NSString * org = @"<ORG_NAME>";
NSString * url = @"<BASE_URL>";
[iOmniataAPI initializeWithApiKeyAndUrl:api_key api_key: UserId:user_id OrgName:org BaseUrl:url];
// Tracks against production API

All Omniata API endpoints are detailed in the REST Overview and related guides.

Configuration

The iOS SDK only supports one time initialization. But the API key and UID can be reset using an SDK method. When using this method, tracking of events will use the updated api_key and user_id specified.

[iOmniataAPI setApiKey:api_key];
[iOmniataAPI setUserId:user_id];

If needed, there is a set of debug level values that you can use to set the log level. Enable logging with the method:

[iOmniataAPI setLogLevel:SMT_LOG_VERBOSE];

Tracking Events

Standard events have their own build-in method for tracking. Custom events can be tracked using a generic method specified below.

Event Method When to call
Load [iOmniataAPI trackLoadEvent]; Whenever the app starts or is brought to foreground.
Revenue [iOmniataAPI trackPurchaseEvent:99.9 currency_code: @"EUR"]; For verified in-app purchases only. The Omniata SDK does not validate or verify purchases.
Advertiser Id [iOmniataAPI trackAdvertiserID]; Upon first load of the application ever. When needed in case the AdId changes.
Custom [iOmniataAPI trackEvent: @"{name}": dictionary]; When the target action or event is detected.

To register custom events parameters use for example:

NSDictionary *dictionary = [[NSDictionary alloc] initWithObjectsAndKeys: @"21", @"cash_balance", @"7", @"level", nil];

Then call the tracking method as

[iOmniataAPI trackEvent: @"quest_complete": dictionary];

The iOS SDK automatically adds event parameters in trackLoadEvent method. These parameters are used for segmentation and reporting. Below is a list of the added parameters.

Parameter Name Details
om_device The device model.
om_platform The platform name, in this case “ios”.
om_os_version Version of the operating system, taken from [[UIDevice currentDevice] systemVersion].
om_sdk_version Version of the SDK.
om_discarded Cumulative count of events the SDK has discarded, because the delivery has failed.
om_ios_bundle_short_version_string Corresponds to CFBundleShortVersionString, in XCode is called “Bundle version string, short”.
om_ios_bundle_version Corresponds to CFBundleVersion, in XCode is called “Bundle version”.
om_ios_bundle_identifier Corresponds to CFBundleIdentifier, in XCode “Bundle identifier”.
om_delta Time difference (seconds) between when the event was created and when it was was sent. Added in all events.

The device model is obtained using the code block:

size_t size; 
sysctlbyname("hw.machine", NULL, &size, NULL, 0); 
char *machine = malloc(size); 
sysctlbyname("hw.machine", machine, &size, NULL, 0); 
NSString *platform = [NSString stringWithUTF8String:machine]; 
free(machine);
return platform;

When the application code asks the SDK to send an event, the event is not immediately sent, instead the event is added to a in-memory queue. A lock is obtained for a very short time while adding. There is a background thread that periodically (every few seconds) polls the persistent storage for events. If there is an event, and network is reachable, the event is sent.

The persistent storage is located in file tmp/smt.events.log in NSHomeDirectory(). That directory is persisted even if the application is updated. By default the SDK uses the Reachability library from Apple to determine the network reachability, nevertheless it’s possible to plug-in a custom reachability check.

A retry mechanism is used for event sending. In the case of event sending fails, the sending system sleeps a certain time and retries. In retried events there is an event parameter om_retry having the value of the number of retries made so far. Sleep time between retries is doubled for each attempt, and reset upon success. The minimum sleep time is one second, i.e. max one event per second is sent. The max sleep is around one minute.

Requesting Content

Channel API request are made by calling loadMessages. Internally the SDK calls the Channel API using HTTP. The call is asynchronously made using [NSURLConnection sendAsynchronousRequest]. The completionBlock that is given as a parameter to loadMessages is called after the Channel API call finishes. In case the request is successful, messages can be retrieved using getChannelMessages.

Currently, a maximum of one Channel API call can be in progress at time. This is also a recommended approach if custom implementations are made to avoid issues with dephased content.

The following is an example usage of the method to request content:

[iOmniataAPI loadMessagesForChannel:40 completionHandler:^(OMT_CHANNEL_STATUS cs){
NSArray* message = [iOmniataAPI getChannelMessages];
}];

Working With Push Notifications

This section covers the client side implementation to enable or disable push notifications. You can find details for configuring your application to allow Omniata to send push notifications to your App in the Setup Push Notifications guide.

In order to enable push notification, you need to request a device token that will enable the apple servers to identify the device. The following snippet will allow you to request a device token (requires iOS version 8):

UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound categories:nil];
[[UIApplication sharedApplication] registerUserNotificationSettings:settings];
[[UIApplication sharedApplication] registerForRemoteNotifications];

The delegate method didRegisterForRemoteNotificationsWithDeviceToken will provide you with the device token that you can pass to the Omniata server by calling enablePushNotifications:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [iOmniataAPI enablePushNotifications:deviceToken];
}

To track the received push notifications you can do so by calling our method trackPushNotification in the delegate method that apple provides : didReceiveRemoteNotification:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))handler {
    [iOmniataAPI trackPushNotification:userInfo];
}

To disable a user from receiving push notifications, you can use the method disablePushNotifications:

[iOmniataAPI disablePushNotifications]

Usage with Swift

To use the iOS SDK with Swift, a bridge header file is needed to import the Omniata iOS SDK header. Example contents of the bridge file are like this:

#ifndef _Bridging_Header_h
#define _Bridging_Header_h
#import "iOmniataAPI/iOmniataAPI.h"
#endif /* _Bridging_Header_h */

Search for SWIFT_OBJC_BRIDGING_HEADER in “Build Settings” of the target, here you need to add the bridge file path to the “Object-C Bridging Header”.

Both iOmniataAPI.framework and SystemConfiguration.framework need to be added to the Link Binary Libraries. A working example can be found in the Apple Watch test project. The iOS SDK methods can be then called in Swift like:

let api_key = "<api_key>"
let user_id = "<uid>"
let org = "<org>"
iOmniataAPI.setLogLevel(SMT_LOG_VERBOSE)
iOmniataAPI.initializeWithApiKey(api_key, userId: user_id, orgName: org)
iOmniataAPI.trackLoadEvent()

Apple Watch Integration

For Apple Watch usage, first you need to expose iOS SDK header in the bridge file as described in the section above. Then, add both iOmniataAPI.framework and SystemConfiguration.framework to the Link Binary Libraries to the WatchKit Extension target.

Check the Apple Watch test project for more details on the implementation.

This article was last updated on April 20, 2017 16:13. If you didn't find your answer here, search for another article or contact our support to get in touch.