iOS SDK: Advanced Options

Singular iOS SDK
Download
Singular iOS SDK version 9.4.0
Compatibility

iOS 8+

Sample App Review our sample app for an example of a complete SDK integration based on best practices.
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Advanced Options

 

Tracking Uninstalls

Note: Uninstall tracking is only available to Enterprise customers.

To let Singular track your app's uninstalls:

  1. Make sure uninstall tracking is enabled for your app in Singular. See Setting Up iOS Install Tracking for instructions.
  2. In the app, send Singular the device token returned from the Apple Push Notification Service (APNS). To pass the device token to Singular use the registerDeviceTokenForUninstall or registerDeviceToken method. Do this before the Singular StartSession call.

If your app doesn't support push notifications yet, see Apple's guide to implementing APNS.

Note:

  • If you are already retrieving a device token from an existing push notification implementation, you can use that value.
  • The APNS token is usually binary data in the native form. Pass the token as received from APNS. If the app alters the token data type pass it as a hex-encoded string, like the following example: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
registerDeviceTokenForUninstall Method (Objective-C)
Description Pass the device token returned from APNS.
Signature + (void)registerDeviceTokenForUninstall:(NSData*)deviceToken;
Usage Example
NSString* apns = @"b0adf7c97302fb522debff5bfba010a9b052";
NSData* data = [apns dataUsingEncoding:NSUTF8StringEncoding];
[Singular registerDeviceTokenForUninstall:data];

Adding Global Properties

The Singular SDK lets you define custom additional properties that you want to send to the Singular servers with every session and event sent from the app. These properties can represent any information you want about the user, the app mode or status, or anything else. Once you set these properties, they are available as dimensions in your reports and you can use them to break down your data.

For example, if you have a gaming app, you can define a property called "Level" and set it initially to "0". Any session and event sent from the app will be sent with "Level": "0". Once the user levels up you reset the property to "1" and so on. You can then get your reports, including sessions, event counts, and revenue data, broken down by user level.

  • You can define up to 5 global properties.
  • They persist between app runs (with the latest value you gave them) until you unset them or the user uninstalls the app.
  • Each property name and value can be up to 200 characters long. If you pass a longer property name or value, it will be truncated to 200 characters.

Setting Global Properties through SingularConfig

To set global properties before initializing the SDK, use the setGlobalProperty method in SingularConfig.

Note that since global properties and their values persist between app runs, the property that you are setting may already be set to a different value. Use the overrideExisting parameter to tell the SDK whether to override an existing property with the new value or not.

setGlobalProperty Method 
Description Set a global property.
Signature setGlobalProperty:(NSString*)key withValue:(NSString*)value overrideExisting:(BOOL)overrideExisting
Usage Example
SingularConfig* config = SingularConfig* config = [[SingularConfig
alloc] initWithApiKey:apiKey andSecret:secretKey];
[config setGlobalProperty:@“example_key” withValue:@“example_value”
overrideExisting:NO];
[config setGlobalProperty:@“test_key” withValue:@“test_value” overrideExisting:YES]; [Singular start:config];

Setting Global Properties After Initialization

Use the following methods to set, unset, and retrieve global properties at any time in the app's run.

setGlobalProperty Method
Description

Set a global property to a given value.

Notes:

  • If the property does not exist yet, and there are already 5 other global properties, the property will not be added.
  • If the property has already been set, the overrideExisting parameter determines whether the existing value will be overridden.
  • The method returns true if the property was set successfully or false otherwise.
Signature (BOOL) setGlobalProperty:(NSString*)key andValue:(NSString*)value overrideExisting:(BOOL)overrideExisting
Usage Example
BOOL result = [Singular setGlobalProperty:@“test_key” 
withValue:@“test_value” overrideExisting:YES];
getGlobalProperties Method
Description Retrieve all the global properties and their current values as a Map.
Signature (NSDictionary*) getGlobalProperties
Usage Example
NSDictionary* props = [Singular getGlobalProperties];
unsetGlobalProperty Method
Description Remove a global property.
Signature (void) unsetGlobalProperty:(NSString*)key
Usage Example
[Singular unsetGlobalProperty:“test_key”];
clearGlobalProperties Method
Description Remove all global properties.
Signature (void) clearGlobalProperties
Usage Example
[Singular clearGlobalProperties];

Using the Singular SDK JavaScript Interface

Singular provides a JavaScript interface that you can use in order to call Singular from within javaScript code in your app.

For example, if you set up the JavaScript interface, you can send events to Singular from JavaScript code as follows:

Singular.event('event'); 
Singular.event('test', JSON.stringify({"a1":"bar",
"a2":"boo", "a3":"baz"}));

The interface supports the following SDK methods:

  • setCustomUserID
  • unsetCustomUserID
  • event
  • revenue

Enabling the JavaScript Interface

Note: Starting in iOS 8.0+ Apple recommends using WKWebView to add web content to your app. Do not use UIWebView or WebView. See Apple's WKWebView documentation for more information.

To enable the JavaScript interface when using WKWebView , you need to add some code to the webView method of the WKNavigationDelegate protocol (this protocol helps you implement custom behaviors triggered when a web view handles a navigation request).

Swift:

extension ViewController: WKNavigationDelegate { 
 func webView(_: WKWebView, decidePolicyFor: WKNavigationAction, 
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { // Singular handler let js = "typeof(Singular)" webView.evaluateJavaScript(js) { (result, error) -> Void in if let resultString = result as? String { if resultString.isEqual("undefined") { do { let contents = try String(contentsOfFile:
Bundle.main.path(forResource: "Singular", ofType: "js")!) self.webView.evaluateJavaScript(contents,
completionHandler: nil) } catch { } } else { print(decidePolicyFor.request) Singular.processJSRequestWK(self.webView,
withURL:decidePolicyFor.request) } } } // rest of your code goes here }

If you are using the older UIWebView (deprecated in iOS 8.0), update the method webView:shouldStartLoadWithRequest:navigationType: in your UIWebViewDelegate file as follows:

Objective-C:

- (BOOL)webView:(UIWebView *)webView 
shouldStartLoadWithRequest:(NSURLRequest *)request
navigationType:(UIWebViewNavigationType)navigationType{ if([[webView stringByEvaluatingJavaScriptFromString:@"typeof(Singular)"] isEqualToString:@"undefined"]) { // Inject Singular.js into the HTML [webView stringByEvaluatingJavaScriptFromString:[NSString
stringWithContentsOfFile:[[NSBundle mainBundle]
pathForResource:@"Singular" ofType:@"js"] usedEncoding:nil error:nil]]; } else { // process request in Singular.js [Singular processJSRequest:webView withURL:request]; } // The rest of your code goes here return true; }

GDPR Compliance

The Singular SDK provides several methods to help you comply with GDPR policies and let Singular know about user consent or non-consent for tracking.

trackingOptIn Method
Description Notify Singular of user consent for tracking (opt-in).
Usage Example Objective-C:
[Singular trackingOptIn];

Swift:

Singular.trackingOptIn()
trackingUnder13 Method
Description Notifying Singular that a user is a minor (under 13).
Usage Example

Objective-C:

[Singular trackingUnder13];

Swift:

Singular.trackingUnder13()
stopAllTracking Method
Description Stopping all tracking activities for this user on this app
Important: Calling this method effectively disables the SDK, even between app restarts (the state is persistent). The only way to turn it off is by calling the resumeAllTracking method
Usage Example

Objective-C:

[Singular stopAllTracking];

Swift:

Singular.stopAllTracking()
resumeAllTracking Method
Description Resuming tracking activities for this user on this app
Usage Example

Objective-C:

[Singular resumeAllTracking];

Swift:

Singular.resumeAllTracking()
isAllTrackingStopped Method
Description Checking the status of tracking for this user on this app
Usage Example

Objective-C:

[Singular isAllTrackingStopped]; // returns true/false

Swift:

Singular.isAllTrackingStopped() // returns true/false
Was this article helpful?