APXOR iOS API Guide

Initializing the SDK

To start tracking with the Apxor iOS SDK, you must first initialize it. To initialize the SDK,

// ObjC
[ApxorSDK initializeApxorSDK];

// Swift
ApxorSDK.initializeApxorSDK()

Identifying Users

ApxorSDK uses Identifier for Advertisers (IFA) to uniquely identify users. In cases where IFA is not available, we use Identifier for Vendors (IFV) for the same.

However, if you want to, you can assign your own user IDs. This is particularly useful if you want to study a specific user with ease. To assign your user ID,

// ObjC
[ApxorSDK setUserIdentifier:@"1729"];

// Swift
ApxorSDK.setUserIdentifier("CustomUserIdentifier")

Log Screen API

ApxorSDK automatically captures screens and their names for most view controllers. In some cases where TabBarController is used, the os won't be providing any notificaitons to capture the screens automatically.

For these cases, we encourage you to log screen events using the following API. Make sure to log the API inside the viewWillAppear function.

// ObjC
- (void)viewWillAppear:(BOOL)animated {

    [ApxorSDK logScreenWithName:@"FirstViewController"];
    /*
      ... your code here ...
     */
}

// Swift
override func viewWillAppear(animated: Bool) {

    ApxorSDK.logScreenWithName("FirstViewController")
    /*
      ... your code here ...
    */
}

User Attributes

There is often additional user identifying information, such as name and email address, connected with the external IDs.

To add some more attributes that are specific to a particular user,

// ObjC
NSDictionary *info = [[NSDictionary alloc] init];
[info setValue:@"spock@vulcan.com" forKey:@"email"];
[ApxorSDK setUserCustomInfo:info];

// Swift
let userInfo = ["email": "spock@vulcan.com"] as [String : AnyObject]
ApxorSDK.setUserCustomInfo(userInfo)

Session Attributes

A Session can be simply defined as a user journey as he opens the app, until he closes the app. There can be various pieces of information that can be very impactful when accumulated in a session. For example, location in a session can be useful to know precisely where the user is utilizing the app most.

To add session attributes that are specific to a session,

// ObjC
NSDictionary *info = [[NSDictionary alloc] init];
[info setValue:@"In a galaxy far far away" forKey:@"location"];
[ApxorSDK setSessionCustomInfo:info];

// Swift
let userInfo = ["location": "In a galaxy far far away"] as [String : AnyObject]
ApxorSDK.setSessionCustomInfo(userInfo)

Reporting Custom Errors

Custom errors describe situations like LOGIN_FAILED, NETWORK_CALL_FAILED and are to be treated differently compared to app events. So these are treated as errors and are shown on the issues page to let you know their impact.

A custom error takes the exception itself and some context (what? OR which?) to make it easy for you to identify. To report a custom error,

// ObjC
NSException* myException = [NSException
                            exceptionWithName:@"FileNotFoundException"
                            reason:@"File Not Found on System"
                            userInfo:nil];
[ApxorSDK reportCustomError:myException withContext:@"customException"];

// Swift
let errorInfo = ["reason": "File Not Found on System"]  as [String : AnyObject]
var customError = NSError(domain:"", code:httpResponse.statusCode, userInfo:nil)
ApxorSDK.reportCustomError(customError, withInfo: errorInfo)

App Events

App events make it easier to analyze user behavior and optimize your product and marketing around common business goals such as improving user retention or app usage. You can also add additional information to any event.

To track an event with the event name and properties.

// ObjC
NSDictionary *info = [[NSDictionary alloc] init];
[info setValue:@"Select Language" forKey:@"event_type"];
[info setValue:@"Valyrian" forKey:@"event_type"];
[ApxorSDK logAppEventForEvent:@"LANG_SELECT" withInfo:info];

// Swift
let eventDict = ["event_type":"Select Language", "event_type":"Valyrian"] as [String : AnyObject]
ApxorSDK.logAppEvent(withName: "EventName", info: eventDict)

Aggregate Events

Events that are not required for an in-depth analysis but are useful as quantitative metrics are called Aggregate Events. Only their aggregate counts will be sent to Apxor to reduce unnecessary transfer and storage of data, minimising overhead and costs.

Example:

Measuring if an article is viewed by a user if it is visible in the view port (visible part of the screen) for five seconds can be logged as an aggregate event to count the impressions of a particular article.

// ObjC
NSDictionary *info = [[NSDictionary alloc] init];
[info setValue:@"Text" forKey:@"card_type"];
[info setValue:@"46Juzcyx" forKey:@"id"];
[ApxorSDK logAppEventWithName:@"Impression" info:info isAggregate:YES];

// Swift
let eventDict = ["card_type":"Text", "id":"46Juzcyx"] as [String : AnyObject]
ApxorSDK.logAppEvent(withName: "Impression", info: eventDict, isAggregate: YES)

Client Events

Events that are logged to reside on the client application are called client events, the data captured is not transferred to Apxor.

These are typically logged to capture behavioural observations and interactions to nudge a user.

Example:

Soft back button, user reaching end of page, etc.

// ObjC
NSDictionary *info = [[NSDictionary alloc] init];
[info setValue:@"com.example.app.SettingsViewController" forKey:@"Screen"];
[ApxorSDK logClientEventWithName:@"SoftBackPressed" info:info];

// Swift
let eventDict = ["Screen":"com.example.app.SettingsViewController"] as [String : AnyObject]
ApxorSDK.logClientEvent(withName: "SoftBackPressed", info: eventDict)

Custom fonts

ApxorSDK supports two types of fonts namely, .ttf(TrueType fonts) and .otf(OpenType fonts). Custom fonts can be used in ApxorSDK's real time actions in two simple steps.

First, adding custom fonts to your application

  • Fonts of your choice and selection are to be added in the Project's Supporting files section Supporting files fonts
  • Edit the Info.plist file to add the font names in the Fonts provided by application Fonts provided by application
  • Ensure the fonts are available in, Build phases --> Copy Bundle resources Copy bundle resources

Second, while configuring the campaigns in the dashboard

  • Enable custom fonts
  • Enter the same exact font file name along with the extension (.ttf or .otf) Custom font

You're all set! 🎉

Note

Font properties like Bold, Italic cannot be used in the dashboard for custom fonts. The exact font file with those properties has to be added in your application.

Handle custom redirection using Key-Value pairs

If your app wants to redirect users based on simple key-value pairs instead using Deeplink URLs or Activity, you can follow below approach

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

  // Your code here
  // ...
  NotificationCenter.default.addObserver(self, selector: #selector(self.onRedirectionClicked(notification:)), name: Notification.Name("APXRedirectionNotification"), object: nil)
}

@objc func onRedirectionClicked(notification: NSNotification) {
  if let kvPairs = notification.userInfo!["info"] {
      print(kvPairs)
      // ...
      // use kvPairs 
      // ...
  }
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Your code here
  // ...
  [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onRedirectionClicked:) name:@"APXRedirectionNotification" object:nil];
}

- (void) onRedirectionClicked:(NSNotification *) notification
{
  NSLog(@"kvPairs: %@", notification.userInfo["info"]);
  // ...
  // use kvPairs 
  // ...
}

To get Apxor Device Identifier

Apxor SDK maintains a unique ID for every user. To get the Apxor Device ID,

NSString *deviceId = [ApxorSDK getDeviceID];

Note

If the deviceID is nil, please retry after a few seconds.

Log Events inside WebView

Note

Make sure you have the latest version of RTA Plugin ( version >= 159)

It is suggested that you log events inside your WebView once the page is completely rendered using Apxor Javascript Interface methods. Based on these events, you can configure Tooltips.

  • Methods exposed from Apxor Javascript Interface

    window.webkit.messageHandlers.logAppEvent.postMessage({"name": "...", "info": "..."});
window.webkit.messageHandlers.logClientEvent.postMessage({"name": "...", "info": "..."});

    Note

    Make sure the keys of the dictionary in postMessage are "name" and "info", do not change them.

  • Examples for logging App Event

    Example:

    Log an event on page load event.

    ...
<head>
  ...
  <script>
    function logApxorEvent(eventName, attributes) {
      if (window.webkit) {
        window.webkit.messageHandlers.logAppEvent.postMessage({"name": eventName, "info": attributes});
      }
    }
  </script>
</head>
<body onload="logApxorEvent('PageLoaded')">
  ...
</body>

    Example (React based web pages):

    Log an event on componentDidMount.

    componentDidMount() {
    if (window.webkit) {
        window.webkit.messageHandlers.logAppEvent.postMessage({"name": 'LoginPageLoaded'});
    }
}

Actions in WebView

Note

Make sure you have the latest version of RTA Plugin ( version >= 144)

Many native applications feature WebViews to display descriptive content and much more. Apxor iOS SDK provides a way to show real-time actions inside that WebView to make the most of it.

Following are the steps in order to show real-time actions in your WebView.

  • Add a tag to the webview (which is to be later provided in the dashboard) as shown.

    • objective-C
    [self.webview setTag:007];
    • Swift
    webview.tag = 007;

  • You have to init the APXWKScriptHandler and call registerEventsAndScripts method to make sure any the calls made in the webview are taken care by the native SDK. It's as follows,

    #import "APXRTAPlugin/APXWKScriptHandler.h"
    • Now, add the following to the init method of your webview
    let apxHandler: APXWKScriptHandler = APXWKScriptHandler.init(handlerFor: webView)
apxHandler.registerEventsAndScripts()

  • Here's how to do the same thing in objective-C.

    • Make sure there's a proper WKUserContentController set to your WkWebView, if not please init it and use that config to initialise your WKWebView.
    WKUserContentController *controller = [[WKUserContentController alloc] init];
WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
config.userContentController = controller;

    #import "APXRTAPlugin/APXWKScriptHandler.h"
...
// add apxor's script handler
APXWKScriptHandler *scriptHandler = [[APXWKScriptHandler alloc] initWithHandlerForWebView:_webView];
[scriptHandler registerEventsAndScripts];

  • Also, make sure there’s an id for the web element that you want to show tooltip on.

Set tag to the WebView

  • In the above example, the element button has an attribute id = change_button, which will used to identify that particular element.

Inapp Sharing content to Whatsapp

Note

Make sure you have the latest version of RTA Plugin ( version >= 154)

The Inapp now supports direct share onto whatsapp. Be sure to include the string "whatsapp" in your application's Info.plist under LSApplicationQueriesSchemes key, as shown below,

Add whatsapp to LSApplicationQueriesSchemes

← AndroidWeb →