Windows Integration Guide : Native

Welcome to the Affle MAAS Windows 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 Windows Native SDK from the link below:
Affle_Windows_Native_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 SDK library that has to be integrated in the application.
3. EasyStorage.dll:This is the Tracker supporting library for Tracker SDK library that has to be integrated in the application.
4. AffleSetting.xml:This is the Trackersettingfile that has to be integrated in the application.
5. SDKProjectSettings.txt : This file contains Tracking URL and other key settings specific to the application.
6. 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

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

1. AffleTrackerSDK_WP_LIB.dll
2. Newtonsoft.Json.dll (Dependency package if not added in project)
3. EasyStorage.dll (Dependency package if not added in project)

easy_storage_dll

Basic Settings

1. Add AffleSetting.xml at project root directory see following screenshot:

add_affle_setting_xml1

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

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

Settings for 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 of your app as shown in the following screenshot:-

setting_down_tracking_1

Tracking Helper class is a single ton class it’s create Instance. You have to initialize like this

tracker = TrackingHelper.GetInstance(Assembly.GetExecutingAssembly(),this);


In-App Stats Tracking

To track in-app metrics 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 =

new_key_in_affle_sett_xml


Optional Settings

Track user engagement while device offline

Key = af_OfflineTracker Value = "1" Value = 1 (inApp offline tracking Off) or 0 (inApp offline tracking ON) * Default value is "0"

Configure maximum duration of user engagement session

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


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_trac_hand

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

Tracking Helper class is a single ton class it’s create Instance. You have to initialize like this.

tracker = TrackingHelper.GetInstance(Assembly.GetExecutingAssembly(),this);

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

Method: In-App Tracker:

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 dict = new Dictionary() { 
            {"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);

Track Purchase Events

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 dict = new Dictionary() { 
            {"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");



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 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 IPushReceiverin main classi.e. mainpage.xaml

Step 2 - Pass second parameter this in mainpage.xaml or wherever you want to access, and wherever you create tracker object pass their second parameter null

Step 3 - Override AFFLEPushReceiver method.

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

step 4 - Override AFFLEPushReceiverDeeplinking method.

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

setting_down_tracking_1


Custom Pop Up

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

custom_pup_up

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
trackingHelper.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
trackingHelper.setEnablePushNotification(true);
}



Browser Deep-linking

Configuring AppName for Mobile Site Deep-linking

Note: Windows phone 8 or Updated version will support Mobile Site Deep-linking.
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: BrowserDeeplinking Class is provided in our SDK.
Step 3: Whenever Mobile Site Deep-linking happens it will Invoke BrowserDeeplinking Class and call a override function MapUri. In this function we will we will replace the page name where you have to navigate or deep-linking.

Please refer to the screenshot for deep-linking.

Deeplinking

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


SDK Testing

1. Check that the application is not/has not already installed on on the emulator or windows phone device
2. Open the tracking link provided in the SDKProjectSetting.txt file via the Windows Phone Browser on the device or the Emulator.
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.