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 - Edit the
Info.plist
file to add the font names in theFonts provided by application
- Ensure the fonts are available in,
Build phases
-->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)
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,
- If you don't already have a bridging header, checkout how to create a bridging header.
- Add the following in the bridging header file.
#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.
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,