Windows Integration Guide: Unity

This document serves as a guide to integrate the Affle MAAS Platform tracker SDK with the chosen Windows application. The SDK helps in tracking:-

• Download/Installs of the application on an Windows Phone device
• In-Application behavioral statistics of the application
• Pushes and Push notification statistics of the application

The SDK provides flexibility to the application developer to choose & integrate one or both the components, based on the requirements.

Getting the Affle Tracker SDK

You can download the latest Windows Phone Unity SDK from the link below:
Affle_Windows_Unity_SDK_6.0.1.zip (Last updated: 16/October/2015)

It should contain the following:

1. AffleTrackerPlugin.unitypackage: This is the Tracker SDK package has to be integrated in the application.

2. AffleSetting.xml: This is the Trackersettingfile that has to be integrated in the application.

3. SDKProjectSettings.txt : This file contains Tracking URL and other key settings specific to the application.

4. BrowserDeeplinking.cs : This class contain code for mobile site deeplinking(support in WP8 and higher version)

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 Visual Studio development suite, provided by Microsoft.



Integration Guide

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

Settings for Download Tracking

Now select and open your main script where you are using Start() and OnGUI() Methods.

Now Initialize the AfflePlugin Class as shown below in screenshot:

sett_down_track_unity

Note : AFFLEPushReceiverCallbck(sending push notification data when you application is in foreground) and AFFLEPushReceiverDeeplinkingCallbck(sending push notification data when you application is in Background or launch from push notification click).

Code :
——
public class YourScript : MonoBehaviour, AfflePlugin.IPushReceiverCallbck
{
AfflePlugin afflePlugin;
void Start () {
afflePlugin = new AfflePlugin(this);
}
public void AFFLEPushReceiverCallbck(string[] AFFLEPushReceiver)
{
string[] AFFLEPushReceiverString = AFFLEPushReceiver;
foreach (string AFFLEPushReceiverData in AFFLEPushReceiverString)
{
// Dump your code for Custom message box
}
}
public void AFFLEPushReceiverDeeplinkingCallbck(string url)
{
// Dump your code for Deep Blinking
}
}



Build

Go to file – > Build Setting -> Select Windows Phone 8, Click on Switch Platform, Now Build or Build and Run.


Open Build Folder

1. Open Build folder, double click on YourProjectName.sln. It will open on Visual studio.

open_build_folder
affle_sett_xml_unity

Add the project settings provided to you in this XML File.

2. For Windows Phone 8, enable the ID_CAP_IDENTITY_DEVICE capability in your WMAppManifest.xml file.

id_cap_identity_device

3. For Push Notification enable the ID_CAP_PUSH_NOTIFICATION Capability in your WMAppManifest.xml

id_cap_push_notification

4. For Enable Web Browser enable the ID_CAP_WEBBROWSERCOMPONENT Capability in your WMAppManifest.xml

id_cap_webbrowsercomponent

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

1. DEBUG Setting: Open your project AffleSetting.xml available under the Supporting Files section in the Project File Navigator on Visual Studio. For Enable debugging we have to set key and value in AffleSetting.xml.

Remark : For retrieving logs from application we have to install WP POWER TOOLS. See following screenshot , but before that we have to close application completely by clicking back button. Open tool select your application, retrieve the txt file.

wp_power_tools

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



Download Conversion Tracking

If the requirement suggests, tracking the download conversion then use the following settings: –

1. Open your project AffleSetting.xml available under the Supporting Files section in the Project File Navigator on Visual Studio.

2. Add a new key in the AffleSetting.xml

Key = af_cid
Value = String
Value =

add_affle_setting_xml


InApp Application Tracking

Note : Before Include InApp Tracker you have to Include Download Tracker, for that please read AffleTracker_WindowsPhone_Unity_SDK_Download_IntegrationGuide.docx

Setting up the InAppStats Tracing Handlers

Declare a Tracker object and instantiate it in your app. choosing where to instantiate a new class is a decision that is unique to your application and code design. Generally, you’d perform this step during creation of the first page of your app as shown in the following screenshot:-

sett_inappstats_trc_hand_unity

Note : You can pass null also in place of extraParams and currency.

The following methods are available for tracking InApp Page/Screen Views, Events, Purchase Events:

Method: InAppTracker:

tracker.InAppTracker(< Screen/Page Name>, < Details about the Screen/Page>, < Event Name>,extraParams);

Example : InAppTracker

tracker. InAppTracker (< Screen/Page Name>, < Details about the Screen/Page>, < Event Name>,extraParams: “PURCHASE_EXTRA_PARAMETER” );
* extraParams value is “KEY-VALUE” formate

Example :
public Dictionary extraParams()
{
Dictionary < string, object> dict = new Dictionary < string, object>() {
{“key1”, “ABC”}, // key1 mapped with FirstName
{“key2”, “XYZ”}, // key2 mapped with LastName
{“key3”, “Male”}, // key3 mapped with Gender
-,
-,
-,
-,
-,
{“key40”, “Gurgaon”} // key40 mapped with City
};

return dict;
}
* Note : ExtraParams key mapping will send by Affle MAAS Platform Team. Our SDk will support maximum 40 keys.

Example for FB_LIKE on Home Screen: –

tracker.InAppTracker(“home” ,”FaceBook_Page”,”fb_like”,extraParams];});

Example for TW_SHARE on Category List Screen: –

tracker.InAppTracker(“Category1List” ,” eventName”,”tw_share”,extraParams);

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

tracker.InAppTracker(“Category2Detail” ,”viewDetail:Title3″,” eventName:rating5″,extraParams);

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

tracker.InAppTracker(“Category2Detail”,”viewDetail:Title4″,” eventName:fb_share”,extraParams);



Purchase Tracking

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

tracker.TrackPurchaseEvent(“ACTUAL_VIEW_NAME” viewDetail:”ACTUAL_DESCRIPTION” pEvent: “PURCHASE_EVENT_NAME ” pTid: “PURCHASE_TRANSACTION_ID” pAmount: “PURCHASE_AMOUNT” pQty: “PURCHASE_QUANTITY” extraParams: “PURCHASE_EXTRA_PARAMETER” pCurrencyCode: “PURCHASE_CURRENCY_CODE”);
* extraParams value is “KEY-VALUE” formate

Example for Purchase on Movie Booking Detail Page: –

tracker.TrackPurchaseEvent (“Movie1Title” viewDetail:null pEvent:”Movie1Name” pTid:”12345″ pAmount:”1000″ pQty:”4″ extraParams:null pCurrencyCode:”INR “);
* Price of 1 Ticket = 250, 4 Tickets = 1000

Example for Purchase on Taxi Booking Detail Page: –

tracker.TrackPurchaseEvent(“TaxiCategory1″ viewDetail:null pEvent:”YellowTaxi” pTid:”abcd22344xxuz” pAmount:”1500″ pQty:”1″ extraParams:null pCurrencyCode:”USD”);
*Price of 1 Ticket = 1500

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

Example :
public Dictionary extraParams()
{
Dictionary < string, object> dict = new Dictionary < string, object>() {
{“key1”, “ABC”}, // key1 mapped with FirstName
{“key2”, “XYZ”}, // key2 mapped with LastName
{“key3”, “Male”}, // key3 mapped with Gender
-,
-,
-,
-,
-,
{“key40”, “Gurgaon”} // key40 mapped with City
};

return dict;
}
* Note : ExtraParams key mapping will send by Affle MAAS Platform Team. Our SDk will support maximum 40 keys.

Dictionary extraParamsDic= {“cardType” : “VISA”,”cardNumber” : “********1007″,”cardName” : “XYZ”, “gatewayType” : “city gateway”,”eventLocation” : “NewDelhi”};
trackingHelper.TrackPurchaseEvent(“Page” ,”Page_detail”,”pevent”,”ptid”,pqty,”pamount”,extraParams(),”Currency”);

Optional Settings

Key = af_OfflineTracker
Value = “1”
Value = 1 (inApp offline tracking Off) or 0 (inApp offline tracking ON)
* Default value is “0”
Key = af_SessionTimeOut
Value Type = String
Value = 3600
* Value is always in Seconds. Example:- 3600 Seconds



Push Notification Tracking

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

Note : Before Include Push Notification you have to Include Download Tracker, for that please read AffleTracker_WindowsPhone_Unity_SDK_Download_IntegrationGuide.docx

push_notification

Enabling Push Notification

Open your project AffleSetting.xml available under the Supporting Files section in the Project File Navigator on Visual Studio. To Enable Push Notification we have to set key and value in AffleSetting.xml.

Key = af_PushNotification
Value = “1”

[Optional Settings]

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


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 Microsoft Push Notification Centre. When We click on push massage open app and handled by AFFLEPushReceiverDeeplinking() method given below.

public void AFFLEPushReceiverDeeplinking(string url)
{
// Collect Push notification data in JSON Format
/ * 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 ShellToastNotificationReceived method in the app delegate. Also developer can set custom/own massage box in this method.

Public void AFFLEPushReceiver(string title, string message, string notificatioJsonString, string urlData)
{
// Build your own custom message box……
}

How to access ShellToastNotificationReceived event in your Application

Step 1 – Inherit AfflePlugin.IPushReceiverCallbck in main class i.e. MainScript class

Step 2 – Pass parameter “this” in MainScript.

Step 3 – Override AFFLEPushReceiverCallbck and AFFLEPushReceiverDeeplinkingCallbck Methods.

Summary: whenever you receive a toast notification and your application is in the foreground then AFFLEPushReceiverCallbck method will triggered.

step 4 – Override AFFLEPushReceiverDeeplinkingCallbck method.

Summary: whenever you receive a toast notification and your application is in the background then AFFLEPushReceiverDeeplinking method will triggered or you receive push notification and your application launch.

sett_down_track_unity

Custom Pop-Up

Whenever our application is in foreground and you want to show your own custom pop up. Integrate below code:

public void AFFLEPushReceiverCallbck(string[] AFFLEPushReceiver)
{
string[] AFFLEPushReceiverString = AFFLEPushReceiver;
foreach (string AFFLEPushReceiverData in AFFLEPushReceiverString)
{
// Dump your code for Custom message box
}
}

Push Notification On/Off Setting from App

Push Notification OFF Setting

Add below line of code in your OFF Switch/CheckBox/Button Event Action/Method.

// Click on OnChecked means Unregistered push notification….
Private void OnChecked(object sender, RoutedEventArgs e)
{
// if false push notification OFF
afflePlugin.setEnablePushNotification(false);
}

Push Notification ON Setting

Add below line of code in your ON Switch/CheckBox/Button Event Action/Method.

// Click on OnUnChecked means Registered push notification….
Private void OnUnChecked(object sender, RoutedEventArgs e)
{
// if true push notification ON
afflePlugin.setEnablePushNotification(true);
}

push_noti_on_sett_unity

Browser Deeplinking

Configuring AppName for Mobile Site Deeplinking

Note : Windows phone 8 or Updated version will support Mobile Site Deeplinking.
For Mobile Site Deeplinking we have to follow some steps :
Step 1: We have to add Protocol with parameters inside Extensions root in WMAppManifest.xml, which is given below. Please refer the screenshot.

WMAppManifest

Step 2 : Go to App.xaml.cs class and add BrowserDeeplinking class in InitializePhoneApplication Method, which is given below.
private void InitializePhoneApplication()
{
RootFrame.UriMapper = new BrowserDeeplinking(); // Add class like this
}
Note : We will provide you BrowserDeeplinking Class with our SDK.
Step 3: Whenever Mobile Site Deeplinking will happened, It will Invoke BrowserDeeplinking Class and call a overrided function MapUri. In this function we will we will replace the Page name where you have to navigate or deeplinking.

Please refer the screenshort for Deeplinking.

MobilesitedeeplinkingUnity

Note :
1) Mobile Site Deeplinking only happened in windows phone 8 and higher version.
2) whenever you want to integrate push notificaton you have to inheritate IPushReceiver in your class and override the above functions which is give in the screenshort.


SDK Testing

1. Ensure that the App does not pre-exist on the Emulator or Windows Phone Device

2. Via the Windows Phone Browser on the device or the Emulator 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 Windows Phone or the Windows Emulator via the Visual Studio.

5. Validate from the logs printed in the debugger of Visual Studio Logs.

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 Windows Phone app. From an Windows Phone Device , conduct the test with the information from the email.