iOS Intergration Guide: PhoneGap

Welcome to the Affle MAAS iOS PhoneGap SDK Integration Section. Our SDK provides developers the flexibility to choose and integrate one or more components based on their requirements.


Getting the Affle Tracker SDK

You can download the latest iOS PhoneGap SDK from the link below:
iOS PhoneGap SDK 6.1.5 (Last updated: 15/March/2016)

It should contain the following:

1. AffleTracker.framework : SDK library for integration.
2. AffleTrackerResources.bundle: SDK library for integration.
3. SDKProjectSettings.txt : Tracking URL and other app specific key settings.
4. JS /AffleTrackerPlugin.js: This is the java script file that has to be integrated in the application.
5. Plugin/ AffleTrackerPlugin.h & AffleTrackerPlugin.m: This is the iOS Class file that has to be integrated in the application.

The step-by-step integration process has been described in detail in the coming sections. Please note any developer attempting to integrate the SDK must have sound knowledge of xCODE development suite by Apple.



Integration

1. In the xcode project, General Project Settings add the AffleTracker.framework file under the Linked Frameworks and Libraries section. Click on Add Other button to add the framework to the project.

add_sdk

2. Add the supporting native frameworks in the above-described manner. These frameworks can be found in the native frameworks list already. (Developer need not click on Add Other button.)
• AdSupport.framework
• CoreTelephony.framework
• CoreData.framework
• UIKit.framework
• Foundation.framework

3. To add the AffleTrackerResources.bundle file, simply drag AffleTrackerResources.bundle file into your Xcode.

4. Also To add an exception to their Info.plist to allow affle http connection for iOS 9.0 and above:
aff_trck_framwork_ios_native

5. To add the AffleTrackerPlugin.js file, In the xcode project. Go www/js floder And simply copy AffleTrackerPlugin.js file into your Xcode.

AffleTrackerPlugin_js

6. Also To add the AffleTrackerPlugin.h and AffleTrackerPlugin.m file, In the xcode project. Go Plugins floder simply drag these class file AffleTrackerPlugin.h and AffleTrackerPlugin.m.

AffleTrackerPlugin_h _m

PhoneGap Plugin Configuration

1. In the xcode project, Go www floder and open config.xml. Add AffleTrackerPlugin feature in config.xml.

< feature name=”AffleTrackerPlugin “>
< param name=”ios-package” value=”AffleTrackerPlugin ” />
< /feature>

AffleTrackerPlugin

Configuring URL’s

1. App Name : Go to the App Info menu in xcode And see URL Types.

xcode_ios_native

We need to configure our application to tell the system what scheme we support. In this example, we want to register “demoapp”.

demoapp_ios_native
That’s it! You’ve configured the app with simple support for the URL scheme “demoapp://”.

2. DEBUG Setting: Open your project info.plist available under the Supporting Files section in the Project File Navigator on xcode.

If your project name is affletrackertest, then the plist file name shall be, affletrackertest-Info.plist

Key =af_DebugMode
Value Type = Boolean
Value = YES (Debug On) or NO (Debug Off)
* Please ensure that the “YES” should be set to “NO” before going live.

Application Deep-linking for Mobile Site Banner

App Url Scheme Testing

Now, to check that our registered URL scheme works, we’ll head out to Safari. Press the “Home” button in the Simulator (or press command-shift-H) to reach the Home Screen. Open Safari. Next, type “demoapp://” in the address bar of Safari. Just as we can with http:// URLs, we’re asking Safari to open the “birdland” scheme. Press Go.

app_url_scheme_testing

You should see that we’ve arrived back in our example project.

In-App URL Scheme Handling

1. In order for your app to respond when it receives a custom URL call, you must implement the application:handleOpenURL method in the application delegate class.

– (BOOL)application:(UIApplication )application openURL:(NSURL )url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
if (!url) {
return NO;
}
// calls into javascript global function ‘handleOpenURL’
NSString* jsString = [NSString stringWithFormat:@”window.setTimeout(function() { \n”
“handleOpenURL(\”%@\”); \n””},1);”, url];
[self.viewController.webView stringByEvaluatingJavaScriptFromString:jsString];
//Affle Deeplinking Tracker Method
[[AffleTracker affleTrackerManager] inAppBrowserDeeplinking:url];
// all plugins will get the notification, and their handlers will be called
[[NSNotificationCenter defaultCenter] postNotification:[NSNotification notificationWithName:CDVPluginHandleOpenURLNotification object:url]];
return YES;
}

2. Add below method in your Index.html. This method implements the functionality of “To mWeb Deep-Link Handeling”.

<script>
function handleOpenURL(url){
// Deeplinking handler code here
}
</script>



Download Conversion Tracking

To track download conversions use the following settings:

1. Open your project info.plist available under the Supporting Files section in the Project File Navigator on xcode. If your project name is affletrackertest, then the plist file name shall be, affletrackertest-Info.plist

2. Add a new key in the Information Property List section of the selected project info.plist

Key = af_cid
Value Type = String
Value = < Use the Affle_CAMPAIGN_ID provided in the SDKProjectSettings.txt >

SDKProjectSettings_txt

3. Include the AffletrackerPlugin.js to your index.html file

< script type=”text/javascript” src=”js/ AffleTrackerPlugin.js”> < /script>

4. Call this method in your index.html. This method implements the functionality of “Tracking the Download Conversion”

AffleTrackerPlugin.affleAppDownloadTracker();

Example:-

< script type=”text/javascript” >
document.addEventListener(“deviceready”, onDeviceReady, true);
function onDeviceReady() {
AffleTrackerPlugin.affleAppDownloadTracker();
}
< /script>



In-App Stats Tracking

To track in-app page views, engagements, events, purchase events & other analytics, use the following settings:

1. Open your project info.plist available under the Supporting Files section in the project file navigator on xcode.
If your project name is affletrackertest, then the plist file name shall be, affletrackertest-Info.plist

2. Add a new key in the Information Property List section of the selected project info.plist

Key = af_InAppTracking
Value Type = Boolean
Value = YES (inApp Event tracking ON) or NO (inApp Event tracking OFF)
* Default value is “YES”


Optional Settings

Track user engagement while device offline

Key = af_OfflineTracker
Value Type = Boolean
Value = YES (inApp offline tracking ON) or NO (inApp offline tracking OFF)
* Default value is “YES”

Configure maximum duration of user engagement session

Key = af_SessionTimeOut
Value Type = String
Value = 3600
* Value is always in Seconds. Example:- 3600 Seconds

Configure maximum duration for network timeout

Key = af_NetworkTimeOut
Value Type = String
Value = 60
* Value is always in Seconds. Example:- 60 Seconds



Example:
optional_settings

3. Include the AffletrackerPlugin.js in your html file from where method to invoke.

< script type=”text/javascript” src=”js/ AffleTrackerPlugin.js” > < /script >

Call the following methods in your program to capture the Page Views, Engagements, Events, Purchase Events & other metrics.

a) Page View

To track your page or screen views in the app call, the method “AffleTrackerPlugin.inAppTrackerEventViewName(viewName, viewDetail, eventName, extraParams)” and pass the View Name that should be displayed on the analytics interface.

Method: inAppTrackerViewName

AffleTrackerPlugin.inAppTrackerEventViewName(:@”ACTUAL_VIEW_NAME”, null, null, null)

Example for Home Screen: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Category2Detail”, “Title2”, null, null);
}
< /script>

Example for Category List Screen: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“CategoryList”, null, null, null);
}
< /script>



b) Page View & Details

To track your page or screen views & extra details in the app call, the method “AffleTrackerPlugin.inAppTrackerEventViewName(viewName, viewDetail, eventName, extraParams)”and pass the View Name & the Detail Description of the page that should be displayed on the analytics interface.

Method: inAppTrackerViewName

AffleTrackerPlugin.inAppTrackerEventViewName(:@”ACTUAL_VIEW_NAME”, “ACTUAL_DESCRIPTION”, null, null)

Example for Category Detail Page with Title 1: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Category1Detail”, “Title1”, null, null);
}
< /script>

Example for Category Detail Page with Title 2: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Category2Detail”, “Title2”, null, null);
}
< /script>



c) Engagement/Events

To track your Engagement/Events in the app, call the “AffleTrackerPlugin.inAppTrackerEventViewName(viewName, viewDetail, eventName, extraParams)” and pass the View Name, the Detail Description of the page & Event/Engagement Name that should be displayed on the analytics interface.

Method:

AffleTrackerPlugin.inAppTrackerEventViewName(:@”ACTUAL_VIEW_NAME”, “ACTUAL_DESCRIPTION”, ” ENGAGEMENT_OR_EVENT_NAME”, null)

Example for FB_LIKE on Home Screen: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Home “, null, “fb_like”, null);
}
< /script>

Example for TW_SHARE on Category List Screen: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Category2Detail”, null,” fb_tw_share”, null);
}
< /script>

Example for RATING on Category Detail Page with Title 3: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Category2Detail”, “Title3″,” rating5″, null);
}
< /script>

Example for FB_SHARE on Category Detail Page with Title 4: –

< script type=”text/javascript”>
function testPageViewTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Category2Detail”, “Title4″,” fb_share”, null);
}
< /script>



d) Engagement/Events Extra Parameter

To track your Engagement/Events in the app, call the method “AffleTrackerPlugin.inAppTrackerEventViewName(viewName, viewDetail, eventName, extraParams)” and pass the View Name, the Detail Description of the page & Event/Engagement Name with extra params that should be displayed on the analytics interface.

Method:

AffleTrackerPlugin.inAppTrackerEventViewName(:@”ACTUAL_VIEW_NAME”, “ACTUAL_DESCRIPTION”, ” ENGAGEMENT_OR_EVENT_NAME”, “EVENT_EXTRA_PARAMETER”)

* extraParams value is “KEY-VALUE” formate.
* In extraParams Neither a key nor a value can be nil.if you need to represent a null value in a dictionary, you should use empty string.

Example for FB_LOGIN on Home Screen with Extra Parameter: –

var extraParamObj = {“key1″:”xyz”,”key2″:”xyz”,”key3″:”xyz@gmail.com”};
// key1 mapped with FirstName // key2 mapped with LastName // key3 mapped with Email ID
*Note:- Extra Params key mapping will be send by Affle MAAS Platform
<script type=”text/javascript”>
function testPurchaseEventTrack () {
AffleTrackerPlugin.inAppTrackerEventViewName(“Home “, null, “fb_like”, extraParamObj);
}
</script>



e) Purchase
track your Purchase Events in the app, call the method “AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(viewName, viewDetail, pevent, ptid, pamount, pqty, pCurrencyCode, extraParams)” and pass the View Name, the Detail Description (if required), Purchase Event Name, Transaction Id, Purchase Amount of Transaction, and Purchase Quantity that should be displayed on the analytics interface.

Method:

AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(“ACTUAL_VIEW_NAME”, “ACTUAL_DESCRIPTION”, “PURCHASE_EVENT_NAME”, “PURCHASE_TRANSACTION_ID”, “PURCHASE_AMOUNT”,” PURCHASE_QUANTITY”, pCurrencyCode:@”PURCHASE_CURRENCY_CODE”,” PURCHASE_EXTRA_PARAMETER”)

* extraParams value is “KEY-VALUE” formate.
* In extraParams Neither a key nor a value can be nil.if you need to represent a null value in a dictionary, you should use empty string.

Example for Purchase on Movie Booking Detail Page: –

< script type=”text/javascript”>
function testPurchaseEventTrack () {
AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(“MovieTitle”, null, “Movie1Name”, “A12345”, “1000”, “4”,”INR”,null);
}
< /script>
* Price of 1 Ticket = 250, 4 Tickets = 1000

Example for Purchase on Taxi Booking Detail Page: –

< script type=”text/javascript”>
function testPurchaseEventTrack () {
AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(“TaxiCategory1”, null, “YelloTaxi”, “A12345xxxuz”, “1500”, “1”,”USD”,null);
}
< /script>
*Price of 1 Ticket = 1500

Example for Credit Purchase on Game Credit Purchase Page With Extra Parameters: –

var extraParamObj = {“key1″:”AFF011″,”key2″:”hello-3″,”key3″:”EA”};
//key1 mapped with cid //key2 mapped Game Name //key3 mapped with Game Brand
*Note:- Extra Params key mapping will be send by Affle MAAS Platform
< script type=”text/javascript”>
function testPurchaseEventTrack () {
AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(“Game1”, null, “Credit”, “A12345xxxuz”, “500”, “1000”,”INR”, extraParamObj);}
< /script>



Application Push Notification

Push Notification or Apple Push Notification Service for IOS (APNS) is a service that allows the Application owner to send data from the server to the application users’ IOS-powered device, and also to receive messages from devices on the same connection.

push_notification

To configure APNS open your project info.plist available under the Supporting Files section in the Project File Navigator on xcode.

If your project name is affletrackertest, then the plist file name shall be, affletrackertest-Info.plist

Add a new key in the Information Property List section of the selected project info.plist

Key = af_PushNotification
Value Type = Boolean
Value = YES
[Optional Settings]
Key = af_pnt
Value Type = String
Value = 1800
* Value is always in Seconds. Example:- 1800 Seconds * Default value is 1800


Configure Push Notifications

We need to make a few modification to the app delegate in order to receive push notifications.Include the AffleTracker.h,AffleTrackerPlugin.h header file in app delegate.
#import < AffleTracker/AffleTracker.h > #import < AffleTrackerPlugin.h >

To register the current device for push, call the method [application registerForRemoteNotificationTypes:] in the app delegate’s [application:didFinishLaunchingWithOptions:] method.

– (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Register for push notifications
[self registerUserDeviceForRemoteNotifications];
return YES;
}
– (void)registerUserDeviceForRemoteNotifications{
if([[AffleTracker affleTrackerManager] getEnablePushNotification]){
if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 8.0){
//For iOS 8.0 and above
[[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
[[UIApplication sharedApplication] registerForRemoteNotifications];
}
else{
//For less than iOS 8.0
[[UIApplication sharedApplication] registerForRemoteNotificationTypes:
(UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert)];
}
}
}


Setting up the Device Registration

1. If the registration is successful, the callback method [application:didRegisterForRemoteNotificationsWithDeviceToken:] in the application delegate will be executed. We will need to implement this method and use it to inform Affle MAAS about this new device.

– (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)newDeviceToken {
// Store the deviceToken in the current installation and send it to ad2campaign.
[[AffleTracker affleTrackerManager] setDeviceToken:deviceToken];
}

2. Include the AffletrackerPlugin.js to your index.html file

< script type=”text/javascript” src=”js/ AffleTrackerPlugin.js”>
< /script>

3. Call this method in your index.html. This method implements the functionality of “To Get Device Token”

AffleTrackerPlugin.getDeviceToken();

Example:-

< script type=”text/javascript”>
function getDeviceToken () {
AffleTrackerPlugin.getDeviceToken();
}
< /script>


Setting up the Push Notification Handlers

Application State : In-Active/Background

1. When a push notification is received while the application is not in the foreground, it is displayed in the iOS Notification Center. When We click on push massage open app and handel by [application:didFinishLaunchingWithOptions:] method in app delegate.

– (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ //Handle receive remote notification
NSDictionary *remoteNotif = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
if(remoteNotif)
{
//Remove push msg and badge from Notification center and app
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:1];
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];
//Send Push open msg to AffleTrackerPlugin class
AffleTrackerPlugin *afflePlugin = [self.viewController getCommandInstance: @”AffleTrackerPlugin” ];
afflePlugin.backgroundPushPayload = remoteNotif;
}
}

2. Include the AffletrackerPlugin.js to your index.html file

< script type=”text/javascript” src=”js/ AffleTrackerPlugin.js”>
< /script>

3. Call this method in your index.html. This method implements the functionality of “To Get Background state PushNotification payload data”
AffleTrackerPlugin. getBackgroundNotifications ();

< script type=”text/javascript”>
document.addEventListener(“deviceready”, onDeviceReady, true);
function onDeviceReady() {
AffleTrackerPlugin. getBackgroundNotifications ();
}
< /script>

4. Push Notication Message Data Handeling(Deep-Link Handeling) to go AffleTrackerPlugin.js and see getBackgroundNotifications method.

getBackgroundNotifications:function(success, failure){
cordova.exec(function(successParam) {
/* Deep link handler code here */
}, failure, “AffleTrackerPlugin”, “getBackgroundNotifications”, []);
}

Application State : Active/Foreground

1. if the notification is received while the app is active, it is up to the app to handle it. To do so, we can implement the [application:didReceiveRemoteNotification] method in the app delegate.

– (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
//Remove push msg and badge from Notification center and app
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:1];
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];
//Send Push open msg to AffleTrackerPlugin class
AffleTrackerPlugin *afflePlugin = [self.viewController getCommandInstance:@” AffleTrackerPlugin”];
[afflePlugin pushNotificationCallBack:userInfo];
}

2. Push Notification Message Data Handling(Deep-Link Handling) to go AffleTrackerPlugin.js and see afflePushNotification.ForgroudPushCallback method.

afflePushNotification.ForgroudPushCallback = function(obj){
/* Deep link handler code


Turning Push Notifications On/Off Setting From App

Push Notification On Setting

1. Include the AffletrackerPlugin.js to your index.html file

< script type=”text/javascript” src=”js/ AffleTrackerPlugin.js”>
< /script>

2. Call this method in your index.html. This method implements the functionality of “Push Notification On Setting”
AffleTrackerPlugin.enablePushNotificationService ();

Example:

< script type=”text/javascript”>
function onDeviceReady() {
AffleTrackerPlugin. enablePushNotificationService ();
}
< /script>

Push Notification Off Setting

1. Include the AffletrackerPlugin.js to your index.html file

< script type=”text/javascript” src=”js/ AffleTrackerPlugin.js”>
< /script>

2. Call this method in your index.html. This method implements the functionality of “Push Notification Off Setting”
AffleTrackerPlugin. disablePushNotificationService ();
Example:-

< script type=”text/javascript”>
function onDeviceReady() {
AffleTrackerPlugin. disablePushNotificationService ();
}
< /script>


APNS Configuration on Server

To Create SSL certificate (.p12) from apple development potal and upload on Affle MAAS Platform platform.

Creating the SSL certificate (.p12)

The first step is to create an App ID and the associated SSL certificate on the Apple Developer website. This certificate (.p12) will allow the Affle MAAS Platform server to send push notifications to the application identified by the App ID.

Generating a Certificate Request

To begin, we’ll need a certificate signing request file. This will be used to authenticate the creation of the SSL certificate.

1. Launch the Keychain Access application on your Mac.

2. Select the menu item Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.

3. Enter your email address and name.

4. Select “Saved to disk” to download the .certSigningRequest file to your desktop.

cert_signing_request

Creating an App ID

Every iOS application installed on your developer device needs an App ID. As a convention, these are represented by reversed addresses (ex. com.example.demoPushApp). For this push app, you can use an App ID you’ve already created, but make sure it does not contain a wildcard character (“*”). The following instructions cover the creation of a new App ID.



SDK Testing

1. Ensure that the App does not pre-exist on the simulator or the ios device.

2. Via the iPhone Safari Browser on the device or the Simulator open the tracking link provided in the SDKProjectSetting.txt file.

3. Click on the banner/Tracking URL provided in the SDKProjectSetting.txt.

4. Now Load the your App on the iPhone or the iOS Simulator via the xCode.

5. Validate from the logs printed in the debugger of xcode.

logs_ios_native

6. You should be able to see the pings from either or both the configured URLs
– af_cid

7. Once you’ve reached the point in your app where the activity should be tracked, check to see if it was recorded in the Event Logs Report. The event should be attributed to the same publisher as the install unless the event uses Re-Engagement.

Note:- The easiest way to test is to send an email with a tracking link, log file and the updated file for the iOS app. From an iOS device (Apple iPhone or iPad), conduct the test with the information from the email.