iOS Integration Guide: Unity

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

It should contain the following:
1. AffleTrackerPlugin.unitypackage: This is the SDK library that has to be integrated in the application.

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

1. Import file “AffleTrackerPlugin.unitypackage” into unity.
Add the corresponding AffleTrackerPlugin.unitypackage right-click your project Assets folder, click Import Package, Click on Custom Package, browse to the location of the AffleTrackerPlugin.unitypackage, and then click on open and in last click on Import. shown in the following screenshots step by step.

Step 1: Now click on Custom Package

include_skd_in_project_1

Step 2 : Click on Open

include_skd_in_project_2

Step 3: Click on Import

include_skd_in_project_3

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

add_sdk

choose-fram-libra-add

3. 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

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://”.


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

When We click on custom URL(mWeb) massage open app and handle by callback method GetWebDeepLinkingMessage invoke in AffleTracker.cs.

public static void GetWebDeepLinkingMessage ()
{
string webDeepLinkingMessageString = getWebDeepLinkingMessage();
Debug.Log (“#####webDeepLinkingMessageString =” + webDeepLinkingMessageString);
/*dump deep linking code here*/
}



Download Conversion Tracking

Open your project info.plist available under the Supporting Files section in the Project File Navigator on xcode.Add 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>

sett-down-conv-trak


Debug Setting
Open your Xcode project info.plist available under the Supporting Files section in the Project File Navigator on xcode.

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.

2. Open your unity project and select your main script where you are using Start() Method.

void Start () {
AffleTracker.instance();
}



In-App Stats Tracking

If the requirement suggests, tracking the inApplication Stats like Page Views, Engagements, Events, Purchase Events & other Analytics, then use the following settings: –

1. Open your project info.plist available under the Supporting Files section in the Project File Navigator on xcode.
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

sett-down-conv-trak

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

a) Page View
To track your page/screen views call the “AffleTracker” class inside your script where you are using Start() and OnGUI() Methods and pass the View Name (that should be displayed on the analytics interface) to the “InAppTrackerEventViewName” method.

Method: InAppTrackerEventViewName

AffleTracker.InAppTrackerEventViewName(“ACTUAL_VIEW_NAME “,null, null, null);

> Example for Home Screen: –

AffleTracker.InAppTrackerEventViewName(“Home”,null, null, null);

> Example for Category List Screen: –

AffleTracker.InAppTrackerEventViewName(“Category List”,null, null, null);

Page View & Details
To track your page/screen views call the “AffleTracker” class inside your script where you are using Start() and OnGUI() Methods and pass the View Name & the Detail Description of the page (that should be displayed on the analytics interface) to the “InAppTrackerEventViewName” method.

Method: InAppTrackerEventViewName

AffleTracker.InAppTrackerEventViewName(“ACTUAL_VIEW_NAME “, “ACTUAL_DESCRIPTION”, null, null);

Example for Category Detail Page with Title 1: –

AffleTracker.InAppTrackerEventViewName(“CategoryDetail”, “Title1”, null, null);

Example for Category Detail Page with Title 2: –

AffleTracker.InAppTrackerEventViewName(“CategoryDetail”, “Title2”, null, null);

Engagement/Events
To track your page/screen views call the “AffleTracker” class inside your script where you are using Start() and OnGUI() Methods and pass the View Name , Detail Description of the view/page & Event/Engagement Name to the “InAppTrackerEventViewName” method that should be displayed on the analytics interface.

Method: InAppTrackerEventViewName

AffleTracker.InAppTrackerEventViewName(“ACTUAL_VIEW_NAME “, “ACTUAL_DESCRIPTION”, “ENGAGEMENT_OR_EVENT_NAME”, null);

Example for FB_LIKE on Home Screen: –

AffleTracker.InAppTrackerEventViewName(“home “, null, “fb_like”, null);

Example for TW_SHARE on Category List Screen: –

AffleTracker.InAppTrackerEventViewName(“Category1List”, null, “tw_share”, null);

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

AffleTracker.InAppTrackerEventViewName(“Category2Detail “, “Title3″, ” rating5″, null);

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

AffleTracker.InAppTrackerEventViewName(“Category2Detail “, ” Title4″, ” fb_share “, null);

Engagement/Events with Extra Parameter
To track your page/screen views call the “AffleTracker” class inside your script where you are using Start() and OnGUI() Methods and pass the View Name , Detail Description of the view/page & Event/Engagement Name with extra key/value params to the “InAppTrackerEventViewName” method that should be displayed on the analytics interface.

AffleTracker.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.

Method: InAppTrackerEventViewName

Example for Movie Booking Event with Extra Parameters: –

public Dictionary extraParams()
{
Dictionary dict = new Dictionary() {
{“key1”, “xyz”},
{“key2”, “abc”},
{“key3”, “xyz@abc.com”}
};
return dict;
}
// 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
AffleTracker.InAppTrackerEventViewName(“MovieList”, ” Booking”, “Movie”, extraParams());

Purchase
To track your page/screen views call the “AffleTracker” class inside your script where you are using Start() and OnGUI() Methods and pass the View Name, the Detail Description (if required), Purchase Event Name, Transaction Id, Purchase Amount of Transaction, and Purchase Quantity with extra key/value params to the “InAppTrackerPurchaseEventViewName” method that should be displayed on the analytics interface.

Method: InAppTrackerPurchaseEventViewName

AffleTracker.InAppTrackerPurchaseEventViewName(“ACTUAL_VIEW_NAME”,”ACTUAL_DESCRIPTION”,”PURCHASE_EVENT_NAME “,”PURCHASE_TRANSACTION_ID”,”PURCHASE_AMOUNT”,”PURCHASE_QUANTITY”,”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: –

AffleTracker.InAppTrackerPurchaseEventViewName(“Movie1Title “,null,” Movie1Name”, “12345” ,”1000″,”4″,”INR”,null);
* Price of 1 Ticket = 250, 4 Tickets = 1000

> Example for Purchase on Taxi Booking Detail Page: –

AffleTracker.InAppTrackerPurchaseEventViewName(“TaxiCategory1″,null,” YellowTaxi “, ” abcd22344xxuz” ,” 1500″,”1″,” USD “,null);
*Price of 1 Ticket = 1500

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

public Dictionary extraParams()
{
Dictionary dict = new Dictionary() {
{“key1”, “E4567456”},
{“key2”, “xyz”},
{“key3”, “Game”},
{“key4”, “visa”}
};
return dict;
}
// key1 mapped with TID // key2 mapped with GameName // key3 mapped with EventType// key4 mapped with CardType
*Note:- Extra Params key mapping will be send by Affle MAAS Platform
AffleTracker.InAppTrackerPurchaseEventViewName(“Game1″,null,” Credit “, “putc445ghfb ” ,” 500″,”1000″,” INR”, extraParams());



Application Push Notification Tracking

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

Basic Settings for Push Notification

1. Open your project info.plist available under the Supporting Files section in the Project File Navigator on xcode.
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]

Push Notification Timer

Key = af_pnt
Value Type = String
Value = 1800
* Value is always in Seconds. Example:- 1800 Seconds * Default value is 1800

option-setting-push-noti

Push Notification Device Registration Setting
Open your unity project and select your main script where you are using Start() Method and call
AffleTracker.RegisterPush() method.

void Start () {
//For Push Notifation Device Registration
AffleTracker.RegisterPush()
}

Push Notification Registration Error and Device Token CallBack Handler
1- If the registration is unsuccessful, the callback method OnDidFailToRegisterForRemoteNotificationsWithError invoke in AffleTracker.cs

void OnDidFailToRegisterForRemoteNotificationsWithError(string error)
{
Debug.Log (“#####RegisterForRemoteNotificationsWithError :” + error);
/*dump error code here*/
}

2- If the registration is successful and you want to use device Token for other push notication service the callback method OnDidRegisterForRemoteNotificationsWithDeviceToken invoke in AffleTracker.cs

void OnDidRegisterForRemoteNotificationsWithDeviceToken(string deviceToken)
{
Debug.Log (“#####Push Device Token :” + deviceToken);
/*dump deviceToken code here*/
}

Push Notification Message 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 handle by callback method GetBackgroundMessage invoke in AffleTracker.cs.

public static void GetBackgroundMessage()
{
string backgroundPushMessageString = getLastBackgroundMessage();
Debug.Log (“#####backgroundPushpayload =” + backgroundPushMessageString);
/*dump deep linking code here*/
}

Application State : Active/Foreground
if the notification is received while the app is active, it is up to the app to handle handel by callback method OnPushNotificationsReceived invoke in AffleTracker.cs.

void OnPushNotificationsReceived(string payload)
{
removeSavePushMessage();
Debug.Log (“#####payload =” + payload);
/*dump deep linking code here*/
}

Push Notification On/Off Setting from App

Push Notification On Setting
Add below line of code in your main script OnGUI () Method where you use togglebutton, switch, checkbox Action.

AffleTracker.PushNotificationsEnable();

Push Notification Off Setting
Add below line of code in your main script OnGUI () Method where you use togglebutton, switch, checkbox Action.

AffleTracker.PushNotificationsDisable();


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

1. 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: that 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 Notigication Tab in side panel and click on setting Menu. A popup came and 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.

x_code

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.