iOS Intergration Guide: Native

Welcome to the Affle MAAS iOS Native 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 Native SDK from the link below:
iOS Native SDK 6.1.5 (Last updated: 14/March/2016)

It should contain the following:

1. AffleTracker.framework : This is the SDK library that has to be integrated in the application.

2. AffleTrackerResources.bundle: This is the SDK library that has to be integrated in the application.

3. SDKProjectSettings.txt : This file contains Tracking URL and other key settings specific to 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 Guide

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.

aff_trck_framwork_ios_native

2. Also 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. Also 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



Configuring App Name for Mobile Site Banner Deep-linking


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 “demoapp” scheme. Press Go.

app_url_scheme_testing

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

In-App URL Scheme Handling

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 {
//Affle Deeplinking Tracker Method
[[AffleTracker affleTrackerManager] inAppBrowserDeeplinking:url];
// Deeplinking handler code here
return YES;
}


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>

selc_project_info_native

3. Include the AffleTracker.h header file in the view controller class of your project.

#import < AffleTracker/AffleTracker.h>

4. Call this method in your main program or viewcontroller file in viewDidAppear Method. This method implements the functionality of “Tracking the Download Conversion”

-(void)viewDidAppear:(BOOL)animated{
[[AffleTracker affleTrackerManager] AffleAppDownloadTracker];
[super viewDidAppear:animated];
}





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

selc_project_info_native

3. Include the AffleTracker.h header file in the class of your project from where the inApp Stat methods have to be invoked.
#import

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/screen views call the “affleTrackerManager” method inside viewDidAppear method of app viewcontroller file and pass the View Name (that should be displayed on the analytics interface) to the “affleTrackerManager” method.

Method: inAppTrackerViewName

[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”ACTUAL_VIEW_NAME” viewDetail:nil eventName:nil extraParams:nil];

Example for Home Screen: –

-(void)viewDidAppear:(BOOL)animated {
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@” home ” viewDetail:nil eventName:nil extraParams:nil];
}

Example for Category List Screen: –

-(void)viewDidAppear:(BOOL)animated {
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category1List ” viewDetail:nil eventName:nil extraParams:nil];
}



b) Page View & Details

To track your page/screen views & extra details call the “affleTrackerManager” method inside viewDidAppear method of app viewcontroller file and pass the View Name & the Detail Description of the page (that should be displayed on the analytics interface) to the “affleTrackerManager” method.

Method: inAppTrackerViewName

[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”ACTUAL_VIEW_NAME” viewDetail:”ACTUAL_DESCRIPTION”eventName:nil extraParams:nil];

• Example for Category Detail Page with Title 1: –

-(void)viewDidAppear:(BOOL)animated {
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category1Detail” viewDetail:”Title1″ eventName:nil extraParams:nil];
}

Example for Category Detail Page with Title 2: –

-(void)viewDidAppear:(BOOL)animated
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category1Detail” viewDetail:”Title2″ eventName:nil extraParams:nil];
}



c) Engagement/Events

To track your Engagement/Events in the app, call the method “affleTrackerManager” and pass the View Name, the Detail Description of the page & Event/Engagement Name that should be displayed on the analytics interface.

Method:

[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”ACTUAL_VIEW_NAME” viewDetail:”ACTUAL_DESCRIPTION” eventName:”ENGAGEMENT_OR_EVENT_NAME” extraParams:nil];

Example for FB_LIKE on Home Screen: –

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”home” viewDetail:nil eventName:”fb_like” extraParams:nil];
});

Example for TW_SHARE on Category List Screen: –

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category1List” viewDetail:nil eventName:”tw_share” extraParams:nil];
});

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

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category2Detail” viewDetail:”Title3″ eventName:”rating5″ extraParams:nil];
});

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

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category2Detail” viewDetail:”Title4″ eventName:”fb_share” extraParams:nil];
});



d) Engagement/Events with Extra Parameter

To track your Engagement/Events in the app, call the method “affleTrackerManager” and pass the View Name, the Detail Description of the page & Event/Engagement Name with extra key/value params that should be displayed on the analytics interface.

Method:

[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”ACTUAL_VIEW_NAME” viewDetail:”ACTUAL_DESCRIPTION” eventName:”ENGAGEMENT_OR_EVENT_NAME” extraParams: 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 Event with Extra Parameters: –

NSDictionary * extraParamsDic = @{@”key1″ : @”Avinash”,@”key2″ : @”Pandey”, @”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
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppTrackerViewName:@”Category2Detail” viewDetail:”Title4″ eventName:”fb_Login” extraParams: extraParamsDic];
});



e) Purchase

To track your Purchase Events in the app, call the method “affleTrackerManager” 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:

[[AffleTracker affleTrackerManager] inAppEventTrackerViewName:@”ACTUAL_VIEW_NAME” viewDetail:”ACTUAL_DESCRIPTION” pEvent:@”PURCHASE_EVENT_NAME ” pTid:@”PURCHASE_TRANSACTION_ID” pAmount:@”PURCHASE_AMOUNT” pQty:@”PURCHASE_QUANTITY” pCurrencyCode:@”PURCHASE_CURRENCY_CODE” extraParams:@”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: –

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppEventTrackerViewName:@”Movie1Title” viewDetail:nil pEvent:@”Movie1Name” pTid:@”12345″ pAmount:@”1000″ pQty:@”4″ pCurrencyCode:@”INR ” extraParams:nil];
}):
* Price of 1 Ticket = 250, 4 Tickets = 1000

Example for Purchase on Taxi Booking Detail Page: –

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
[[AffleTracker affleTrackerManager] inAppEventTrackerViewName:@”TaxiCategory1″ viewDetail:nil pEvent:@”YellowTaxi” pTid:@”abcd22344xxuz” pAmount:@”1500″ pQty:@”1″ pCurrencyCode:@”USD” extraParams:nil];
});
*Price of 1 Ticket = 1500

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

NSDictionary * extraParamsDic = @{@”key1″ : @”VISA”,@”key2″ : @”********1007″, @”key3″ : @”XYZ”, @”key4″ : @”city gateway”, @”key5″ : @”NewDelhi”};
// key1 mapped with cardType // key2 mapped with cardNumber // key3 mapped with userName // key4 mapped with gatewayType // key5 mapped with eventLocation
*Note:- Extra Params key mapping will be send by Affle MAAS Platform
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ [[AffleTracker affleTrackerManager] inAppEventTrackerViewName:@”Game1″ viewDetail:nil pEvent:@”Credit” pTid:@”putc445ghfb” pAmount:@”500″ pQty:@”1000″ pCurrencyCode:@”INR” extraParams: extraParamsDic];
});



Application Push Notifications

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 Notification

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

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

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];
}




Setting up the Push Notification Handlers

Application State : In-Active/Background

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.

– (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 Affle MAAS
[[AffleTracker affleTrackerManager] inAppPushNotification:remoteNotif];
//Handel Push Notification Msg Data (Deep-Link Handeling)
[self notificationReciveEventHandeler:remoteNotif];
}
}

Add below method in app delegate for Push Notication Message Data Handeling(Deep-Link Handeling).

-(void) notificationReciveEventHandeler:(NSDictionary *)eventData{
// Deep link handler code here
}

Application State : Active/Foreground

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. Also devloper can set custom/own massage box in this method.

– (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 Affle MAAS
[[AffleTracker affleTrackerManager] inAppPushNotification:userInfo];
/*****
Developer can set own AlertView/Message Box UI here. Then call method ([self notificationReciveEventHandeler:userInfo];) on Alert/Message Box UI Action event for depp link handeling.
***/
//Handel Push Notification Msg Data (Deep-Link Handeling)
[self notificationReciveEventHandeler:userInfo];
}

Add below method in app delegate for Push Notication Message Data Handeling(Deep-Link Handeling).

-(void) notificationReciveEventHandeler:(NSDictionary *)eventData{
// Deep link handler code here
}




Push Notification On/Off Setting from App

Push Notification On Setting

Add below line of code in your On UISwitch/UIButton Event Action/Method.

[[AffleTracker affleTrackerManager] setEnablePushNotification:YES];
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 iOS than 8.0
[[UIApplication sharedApplication] registerForRemoteNotificationTypes:
(UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert)];
}

Push Notification Off Setting

Add below line of code in your Off UISwitch/UIButton Event Action/Method.

[[AffleTracker affleTrackerManager] setEnablePushNotification:NO];
[[UIApplication sharedApplication] unregisterForRemoteNotifications];




APNS Configuration on Server

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

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.

1. Navigate to the Apple Developer Member Center website, and select Certificates, Identifiers & Profiles.
2. Select Identifiers from the iOS Apps section.
3. You will see a list of your iOS App IDs. Select the “+” button to register a new App Id.

ios_app_id_add

4. Enter a name for your new App ID, then make sure to select the checkbox next to Push Notifications under App Services.

app_id_discription

5. Choose an App ID Prefix. The default selection should be correct in most cases.

6. Under App ID Suffix, select Explicit App ID. Enter your iOS app’s Bundle ID. This string should match the Bundle Identifier in your iOS app’s Info.plist.

app_id_suffix

7. Select “Continue” and make sure that all the values were entered correctly. Push Notifications should be enabled, and the Identifier field should match your app’s Bundle Identifier (plus App ID Prefix). Select “Submit” to finalize the registration of your new App ID.



Configuring your App ID for Push Notifications – Development Mode

Now that you’ve created an App ID (or chosen an existing Explicit App ID), it’s time to configure the App ID for Push Notifications.

1. Select your newly created App ID from the list of iOS App IDs, then select “Settings”.

app_id_from

2. Scroll down to the Push Notifications section. Here you will be able to create both a Development SSL Certificate, as well as a Production SSL Certificate. Start by selecting “Create Certificate” under “Development SSL Certificate”.

push_notification_enable

3. The next screen will show instructions for creating a Certificate Signing Request (CSR). This is the same .certSigningRequest file you created earlier in Section 1. Select “Continue”, then select “Choose File…” and locate the .certSigningRequest you created in Section 1.

4. Select “Generate”. Once the certificate is ready, select “Done” and download the generated SSL certificate from the “iOS App ID Settings” screen.

push_notifi_down_certi

5. Double click on the downloaded SSL certificate to install it in your Keychain.

6. In Keychain Access, under “My Certificates”, find the certificate you just added. It should be called “Apple Development IOS Push Services: “.

apple_dev_ios_push_services

Right-click on it, select “Export Apple Development IOS Push Services:…”, and save it as a .p12 file. You will be prompted to enter a password which will be used to protect the exported certificate. Do not enter an export password when prompted! Note that you might have to enter your OS X password to allow Keychain Access to export the certificate from your keychain.

export_apple_dev_ios_push_services

If the Personal Information Exchange (.p12) option is grayed out in the export sheet, make sure “My Certificates” is selected in Keychain Access. If that does not help, double check that your certificate appears under the login keychain. You can drag and drop it into login if needed.

Note that you’ve just enabled Push Notification for your app in development mode. Prior to releasing your application on the App Store, you will need to repeat steps of this section, but select “Production Push SSL Certificate”, as covered in Next.



Configuring your App for Push Notifications – Distribution Mode

1. In Section 1.3., you configured your App ID for Push Notifications in Development. select “Production Push SSL Certificate”.

2. Your App ID should now be configured for both Development and Distribution push notifications. Make sure to download the new Production SSL Certificate from the App ID Settings screen.

app_id_sett_screen_ios_native
Double click on the downloaded SSL certificate to install it in your keychain. Right-click on it and export it as a .p12 file. Again, don’t enter an export password when prompted.

Note: Once you have uploaded a production push certificate to Affle MAAS Platform, you will only be able to target devices using a distribution provisioning profile. Devices running an app signed with a development provisioning profile will need to install the newly provisioned build again.



Upload the SSL certificate(.p12) on ad2campaign

Login on Affle MAAS Platform and go to Push Notificationsettings to upload above SSL certificate(.p12).

upload_ssl_certificate




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.