Integration
Product Guides

iOS

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 the 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. Apart from this you can log a custom user identifier that you use to uniquely identify users in your app.

This identifier would be very instrumental specially when exporting data of a certain campaign or survey to your analytics system to create a cohort and measure the results of the campaign.

Similarly, when you are importing data to Apxor from your system that your marketing / product / data science team has identified and want to run campaigns specifically to them the custom user identifier will serve as the bridge to communicate between your systems and Apxor effectively.

Here is how you can set your user identifier for Apxor to recognise your users :

// ObjC
[ApxorSDK setUserIdentifier:@"1729"];
// Swift
ApxorSDK.setUserIdentifier("CustomUserIdentifier")

Setting up campaign triggers, capturing data for targetting and goal tracking​

The product/marketing or the growth team lists out the use cases with an idea of when to launch and to whom to launch. To do this we need to capture data in the form of events. Let us consider the following use case as an example :

App Events​

In the above scenario, we want to trigger the campaign for users who have spent 'x' seconds and haven't tapped on a product. To understand that if the user has tapped the product we should log an event along with its attributes as follows to capture data:

Similarly if you want to send promotions to users who have viewed at least five products of the category shoes in the last three days or you want to measure how many people added an item to a cart from the campaign as a goal all this information is captured in the form of events.

These types of events are classified as app events - the data that is transferred to the servers at Apxor where you can segment users based on historic behavior or measure your goals as specified above.

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)

User Attributes

Personalizing and targeting by user persona​

We can personalize the messaging copy in the experiences we build for the user or target based on his persona using information that is centric to individual users. Let us consider the following example where we know the user is an English with Gold membership.

This information helps to tailor content in English to that specific user and gives us the flexibility to different messaging to different membership tiers. This is how the information captured here is used for segmenting.

Similarly capturing attributes like Name can help to personalize your message copy where it reads Hi {username} can't find your product? where the username is replaced by the attribute value of the property from the nudges dashboard along with providing meaningful defaults in their absence.

This is how you log user information to Apxor :

// 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)

Client Events

In the below scenario, let's assume you want to launch a survey when the soft back button is pressed asking the user for product feedback. In this, we don't need to capture the data of how many people pressed the back button which is useless and it bloats your event storage as it is a high-frequency event which increases your cost unnecessarily. This data point doesn't potentially answer any of your product questions and hence there is no ROI in storing data from this event.

So for such scenarios where we need the behavioral data to launch a campaign or to collect feedback, which doesn't provide ROI on storing for measuring goals, answering your product questions or segmenting your target audience, we log these events as Client Events which involves zero transfer of data and is used only to set up your triggers on behavioral information from the user.

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 behavioral 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)

Track Screens

In the scenario discussed in this guide, how will we know if the user has spent thirty seconds on the home screen and did not click on the product? For this reason, it is important to use track the screens to set them up as triggers and also to capture the time spent on the screens.

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 notifications 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 ...
    */
}

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)

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.

Adding custom fonts to your application

  • Fonts of your choice and selection are to be added in the Project's Supporting files section

  • Edit the Info.plist file to add the font names in the Fonts provided by application

  • Ensure the fonts are available in, Build phases --> Copy Bundle resources

While configuring the campaigns in the dashboard

  • Enable custom fonts

  • Enter the same exact font file name along with the extenstion (.ttf or .otf)

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

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

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.

    // ObjC
[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.

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

Dynamic Script Text in actions

A new capability of writing dynamic text in actions (Tooltips & InApps) had been introduced in latest release of Apxor SDK plugins.

You can write a script (a new language that Apxor is created which somewhat looks like Javascript) instead of plain text to substitue user and session properties that you have already logged to Apxor SDK or you can substitute a text element from your application or hidden text that you set it as keyed tag (apx_view_tag).

The Apxor Language

The Apxor language looks similar to Javascript with some modifications.

We assume every dynamic param that you want to substitute in a text is a pre-defined variable that you can create upfront in the Script dialog that Apxor Dashboard provides to you.

We support following operators and keywords as part of our language specification

Unary Operators

! (Negation)

Logical Operators

&& (Logical AND)

|| (Logical OR)

Mathematical Operators

+ (Arithmetic Addition)

- (Arithmetic Subtraction)

* (Arithmetic Multiplication)

/ (Arithmetic Division)

% (Arithmetic Modulo)

Comparison Operators

< (Less than)

<= (Less than or Equals)

> (Greater than)

>= (Greater than or Equals)

== (Equality)

!= (Not Equality)

contains (Checks if a string contains another string)

Keywords

httpGet, onSuccess, onError will be used to make a HTTP GET API call

format will be used to format a string

if, else will be used to write conditional evaluation

true, false boolean keywords

toInt will be helful to convert double/float values to integer

Examples

Note:

Assume the following variables are defined

  • UserName (User Property)

  • RewardPoints (User Property)

  • IsSubscribed (User Property)

  • Subscribed (API JSON response parameter user.is_subscribed)

  • Simple formatting of string

format(
  "Hello {}. We are exicted to give you {} reward points. You can see these points in Rewards section",
  UserName,
  toInt(RewardPoints)
);

  • Conditional Dynamic Text

if (!IsSubscribed && RewardPoints < 500) {
  format(
    "Hello {}, you are just {} points away to get free subscription",
    UserName,
    500 - RewardPoints
  );
} else {
  format("Hello {}, You are already subscribed", UserName);
}

  • API call

httpGet(format("https://your-server.com/your-api?userName={}", UserName))
  .onSuccess(() => {
    if (SubScribed) {
      format("Hello {}, you are already subscribed", UserName);
    } else {
      format("Hello {}, you are not subscribed yet", UserName);
    }
  })
  .onError(() => format("Something went wrong. Try again later"));

Yeah! You are ready to create your first Campaign or Survey

PreviousAPI GuidesNextWeb

Last updated