Windows Integration Guide : PhoneGap

Welcome to the Affle MAAS Windows 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 Windows Phone PhoneGap SDK from the link below:
Affle_Windows_PhoneGap_SDK_6.0.1.zip (Last updated: 16/October/2015)

It should contain the following:

1. AffleTrackerSDK_WP_LIB.dll: This is the Tracker SDK library that has to be integrated in the application.
2. Newtonsoft.Json.dll: This is the Tracker supporting library for Tracker
3. AffleSetting.xml: This is the Tracker setting file that has to be integrated in the application.
4. JS /AffleTrackerPlugin.js: This is the java script file that has to be integrated in the application.
5. Plugin/ AffleTrackerPlugin.cs: This is the Windows Phone C Sharp Class file that has to be integrated in the application.
6. BrowserDeeplinking.cs : This class contain code for mobile site deeplinking(support in WP8 and higher version)
7. 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 Visual Studio development suite, provided by Microsoft.



Integration Guide

1) Add the corresponding AffleTrackerSDK_WP_LIB.dll for your platform (Windows Phone 7 / 8 / 8.1) as a Reference in your project: right-click your project folder, click Add Reference, browse to the location of the .DLL file, and then select it as shown in the following screenshot.

Add following DLLs:-
AffleTrackerSDK_WP_LIB.dll and Newtonsoft.Json.dll (Dependency package if not added in project)

add_dll

2) Add AffleSetting.xml at project root directory refer the following screenshot :-
affle_sett_xml

3) In the Application project, Go www/js floder and add AffleTrackerPlugin.js file. Refer the following screenshot :-
affle_tracker_plugin_js

4) In the Application project, Go Plugins floder and add file AffleTrackerPlugin.cs . Refer the following screenshot :-
affle_tracker_plugin_cs

Basic Settings for PhoneGap Plugin

1. In the Application project, Go www folder and open config.xml. Add AffleTrackerPlugin in config.xml file. Refer the following screenshot :-

< widget>
< plugins>
< plugin name=” ad2campaign_WINDOWS_SDK.Plugins.AffleTrackerPlugin ” />
< /plugins>
< /widget>

affle_tracker_plugin

Basic Settings For App

1. Add the project settings provided to you in the XML File (AffleSetting.xml)

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

To track download conversions 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 = < Use the Affle_CAMPAIGN_ID Provided in the SDKProjectSettings.txt >

new_key_in_affle_sett_xml

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>

Settings for Download Tracking
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(eg : MainPage.xaml.cs) of your app as shown in the following
set_for_dow_tracking



InApp Stats Tracking

To track in-app page views, engagements, events, purchase events & other analytics, 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 = Affle_CAMPAIGN_ID provided in the SDKProjectSettings.txt >

new_key_in_affle_sett_xml

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

new_key_in_affle_sett_xml

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

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

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

a) Purchase
Track your Purchase Events in the app, call the method “AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(viewName, viewDetail, pevent, ptid, pamount, pqty,extraParams,pCurrencyCode)” and pass the View Name, the Detail Description (if required), Purchase Event Name, Transaction Id, Purchase Amount of Transaction, Purchase Quantity , extraParams define below and Purchase Currency Code, 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”,” PURCHASE_EXTRA_PARAMETER”,”PURCHASE_CURRENCY_CODE”);
* PURCHASE_EXTRA_PARAMETER (extraParams) value is “KEY-VALUE” (JSON) formate

Example for Purchase on Movie Booking Detail Page without extraParams and currency :-

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

Example for Credit Purchase on Movie Booking Detail Page With Extra Parameters: –

< script type=”text/javascript”>
var extraParams = {
“key1” : “ABC”, // key1 mapped with FirstName
“key2” : “XYZ”, // key2 mapped with LastName
“key3” : “Male”, // key3 mapped with Gender
-,
-,
-,
-,
-,
-,
“key40” : “Gurgaon” // key40 mapped with City
} ;

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


function testPurchaseEventTrack() {
AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(“MovieTitle”, null, “Movie1Name”, “A12345”, “1000”, “4”,extraParams,”INR”);
}
< /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”,null,”INR”);
}
< /script>
*Price of 1 Ticket = 1500

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

var extraParamObj = {“cid”:”AFF011″,”gname”:”hello-3″,”brand”:”EA”};
< script type=”text/javascript”>
function testPurchaseEventTrack() {
AffleTrackerPlugin.inAppTrackerPurchaseEventViewName(“Game1”, null, “Credit”, “A12345xxxuz”, “500”, “1000”,extraParamObj,”INR”);
}
< /script>


b) 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.
Note : you can pass extraParams = null also.
Method: inAppTrackerViewName

AffleTrackerPlugin.inAppTrackerEventViewName(“ACTUAL_VIEW_NAME”, null,null,extraParams);

Example for Home Screen: –

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

Example for Category List Screen: –

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


c) 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,extraParams);

Example for Category Detail Page with Title 1 :-

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

Example for Category Detail Page with Title 2: –

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



d) Engagement/Events
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 that should be displayed on the analytics interface.
Method:

AffleTrackerPlugin.inAppTrackerEventViewName(“ACTUAL_VIEW_NAME”, “ACTUAL_DESCRIPTION”,” ENGAGEMENT_OR_EVENT_NAME”,”extraParams”);

Example for FB_LIKE on Home Screen: –

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

Example for TW_SHARE on Category List Screen: –

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

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

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

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

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



Settings for In-App Stats Tracking
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(eg : MainPage.xaml.cs) of your app as shown in the following
set_for_dow_tracking



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

Enabling Push Notifications

Open your project AffleSetting.xml available under the Supporting Files section in the Project File Navigator on Visual Studio. For 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 message open app and handled by AFFLEPushReceiverDeeplinking(values) method given below.
Call this method in your index.html. This method implements the functionality of “To Get Background state PushNotification payload data”

< script type=”text/javascript”>
function AFFLEPushReceiverDeeplinking(values) {
// values contain the push notification data in json format………
/ * Deep link handler code here */
}

Application State : Active/Foreground or Custom Pop Up
if the notification is received while the app is active or in foreground, it is up to the app to handle it. To do so, we can implement the AfflePushReceiver method in the app delegate. Also developer can set custom/own massage box in this method.

Call this method in your index.html.

< script type=”text/javascript”>
function AfflePushReceiver(arg1, arg2, arg3, arg4)) {
// arg1, arg2, arg3, arg4 contain the push notification data in json format………
// create your own custom pop whenever your app is in foreground and you receive push notification
}
< /script>


Push Notification 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.setPushNotificationService ();
Example:-

< script type=”text/javascript”>
function onRadioButton or onSwitch() {
// value should be bool (true or false)
// if true push notification ON
AffleTrackerPlugin. setPushNotificationService (value);
}
< /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. setPushNotificationService ();
Example:-

< script type=”text/javascript”>
function onRadioButton or onSwitch() {
// value should be bool (true or false)
// if false push notification OFF
AffleTrackerPlugin. setPushNotificationService (value);
}
< /script>

Settings for Push Notification Tracking

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(eg : MainPage.xaml.cs) of your app as shown in the following
set_for_dow_tracking

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

Call this method in your index.html. This method implements the functionality of “To Get Background state mobile site deeplinking payload data”

Example:-

< script type=”text/javascript”>
function AFFLEBrowserPushReceiverDeeplinking(values) {
// values contain the push notification data in json format………
/ * Handle Mobile Site Deeplinking code here */
}
< /script>

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.