# Mobile Pixel SDK

- [Overview](#overview)
- [Mobile OS requirements](#mobile-os-requirements)
- [Pixel Parameters](#pixel-parameters)
  - [Additional Parameters](#additional-parameters)
- [MediaMath Mobile SDK for Apple iOS (Swift)](#mediamath-mobile-sdk-for-apple-ios-swift)
- [Native implementation on iOS](#native-implementation-on-ios)
  - [Native iOS Example](#native-ios-example)
  - [iOS Learning Resources](#ios-learning-resources)
- [Native implementation on Android](#native-implementation-on-android)
  - [Native Android Example](#native-android-example)
- [Native implementation on Windows and Windows Phone](#native-implementation-on-windows-and-windows-phone)
- [Implementing a Pixel for tracking app installs](#implementing-a-pixel-for-tracking-app-installs)
- [Generating SHA 256 Hashes for Deterministic Reinforcement](#generating-sha-256-hashes-for-deterministic-reinforcement)
  - [Android](#android)
  - [iOS - Swift3](#ios---swift3)
  - [iOS - ObjC](#ios---objc)
- [Getting Support](#getting-support)


# Overview

MediaMath pixels allow MediaMath Platform clients to track activity on their website and/or in their mobile apps for the purposes of reporting attributed conversions, app installations, and later remarketing campaigns.

This document is intended for the mobile app developer. The instructions below provide guidance on how to trigger the MediaMath Platform pixel by embedding MediaMath’s Pixel SDK,or simulating a pixel fire via web-view within the Advertiser’s App.

If a mobile app uses web views, developers can use the typical web approach of triggering pixels with a HTTP call to MediaMath’s MathTag servers in the form of an `<img>` or `<script>` tag loaded on an advertiser’s website. However, native mobile apps with no web views require a little more instruction.

MediaMath provides libraries via the SDK that trigger pixels fires directly from iOS and Android apps using simple native function calls. Alternatively, developers can manually generate pixels to fire within their apps by constructing and sending HTTP requests, but they will need to populate the IDFA and/or Android AID into the HTTP call to the MathTag pixel server.

In addition to the instructions below, the app developer should be provided with the following from their marketing team:

- TerminalOne Advertiser ID (value from `&mt_adid=` of a JS pixel from a website)
- TerminalOne Pixel ID (value from `&mt_id=` portion of a JS pixel from a website)
- Instructions on the exact interactions within the mobile app for which a pixel fire should be triggered


Note: Your marketing team can create more than one pixel, with each individual Pixel ID representing different events that are meaningful. Please ask for clarification on what particular user interaction corresponds to a given `pixel_id`.

# Mobile OS requirements

To identify users across apps, MediaMath uses the device-specific advertising identifier provided by the mobile OS, known as the IDFA on iOS, the AAID on Android, and the Advertising ID on Windows and Windows Phone.

For your app to use these identifiers, the following OS versions are required:

- **iOS:** iOS 7 or later.
  - iOS 10: IDFA is not available if Limit Ad Tracking is enabled
- **Android:** Android 2.3 or later
  - The advertiser's Android app must include the Google Play Services SDK to retrieve the AAID (and, therefore, to fire MathTag pixels).
  - Android apps using the AAID must also include a privacy policy. [See this FAQ page.](https://support.google.com/googleplay/android-developer/answer/6048248)
- **Windows:** Windows 8.1 or later, or Windows Phone 8.1 or later
  - Windows and Windows Phone apps that use the Advertising ID must comply with Microsoft's [developer policies](https://msdn.microsoft.com/en-us/library/windows/apps/dn764944.aspx#POL_10_10) regarding privacy and user choice.


# Pixel Parameters

For each of the methods of implementing pixels in mobile apps described in this document, a developer will need the following information from their marketing team:

| Field | Required? | Description | Format |
|  --- | --- | --- | --- |
| ADVERTISER_ID | Required | TerminalOne Advertiser ID (value from &mt_adid= of a JS pixel from a website) | String |
| PIXEL_ID | Required | TerminalOne Pixel ID (value from &mt_id= of a JS pixel from a website) | String |
| ADDITIONAL_PARAMETERS | Optional | Additional information to send to TerminalOne at the time of pixel fire. | String. URL-encoded string of parameters (e.g.`"v1=data1&v2=data2&s1=data3"`) |



```json
{
  "url": "https://pixel.mathtag.com/event/mob",
  "method": "get",
  "query": {
    "mt_adid": "",
    "mt_id": "",
    "mt_uuid": "",
    "mt_idt": "",
    "": ""
  }
}
```

## Additional Parameters

Additional Parameters can be used for

- Revenue tracking: To send a pixel tracking the value of an order, include something like v1=99.99&s1=USD.
- Deterministic reinforcement: To take advantage of MediaMath ConnectedID, include a mt_exem or mt_excl string parameter


The value for the `mt_exem` (for hashed emails, `'john@email.com'`) or the `mt_excl` (for hashed account ids, e.g. 'john2015', '829852', etc) parameter must be the SHA-256 hashed email address of the consumer, when available at the time of pixel fire.

The hashing of the email address is not performed by the MediaMath Pixel SDK. The app developer must SHA-256 hash the email address.

# MediaMath Mobile SDK for Apple iOS (Swift)

To integrate the MathTag Mobile SDK on iOS, follow these steps:

1. Checkout the [iOS SDK](https://github.com/MediaMath/ios-sdk) and include it as a product in your workspace.
2. Add the following declaration to all source files from which you want to fire pixels:


`import MMPixelSDK`
3. Optionally, you can turn on debugging by including the following call directly before firing a pixel:

`MMPixel.setDebugOutput(debug: true)`

This will log debugging information about pixel fires to your Xcode console window.

To fire a pixel, invoke the following method, substituting the information from the above [table of parameters](#pixel-parameters):

MMPixel.report(advertiser: ADVERTISER_ID, pixel: PIXEL_ID, addlParams: ADDITIONAL_PARAMETERS)

The iOS Swift SDK also allows passing in a `[String: String]` key/value dictionary for the `addlParams` argument. In this case, the `mt_exem` and `mt_excl` parameters are automatically SHA-256 hashed.

**Important note regarding limit ad tracking:** If “Limit Ad Tracking” is enabled on the device, MediaMath requires app developers to randomize the IDFA or AAID. This will require that the app developer retrieve the IDFA or AAID for population into the HTTP request. Mediamath's privacy policy *requires* honoring the Limit Ad Tracking settings of a device by using a random UUID in place of the identifier.

# Native implementation on iOS

To fire a MathTag pixel on iOS devices without the SDK, follow these steps in your app’s code.

1. Request the iOS Identifier for Advertising (IDFA).
2. Prepare the pixel URL for the HTTP request using the template: `https://pixel.mathtag.com/event/mob?mt_adid=ADVERTISER_ID&mt_id=PIXEL_ID&mt_uuid=UUID&mt_idt=idfa&ADDITIONAL_PARAMETERS`
3. Send the HTTP request to fire the pixel by instantiating a hidden UIWebView or WKWebView.


To fire additional pixels with other pixel IDs, repeat steps 2 and 3 above, updating the `PIXEL_ID` and `ADDITIONAL_PARAMETERS` in the URL as necessary.

## Native iOS Example


```csharp
import AdSupport
...
let myIDFA: String?
// Check if "Limit Ad Tracking" is Enabled
if ASIdentifierManager.sharedManager().advertisingTrackingEnabled {
  // use the IDFA
  myIDFA = ASIdentifierManager.sharedManager().advertisingIdentifier.UUIDString
}
else {
  // use a random UUID
  myIDFA = NSUUID().UUIDString
}
```

## iOS Learning Resources

- [iOS Developer Library - AdSupport Framework Reference](https://developer.apple.com/library/prerelease/ios/documentation/DeviceInformation/Reference/AdSupport_Framework/index.html)
- [Stack Overflow - How to retrieve iPhone IDFA](http://stackoverflow.com/questions/12944504/how-to-retrieve-iphone-idfa-from-api)


# Native implementation on Android

To manually fire a MathTag pixel on Android devices, follow these steps in your app’s code.

1. Integrate the [Google Play Services SDK](http://developer.android.com/google/play-services/setup.html) and [request the Android Advertising ID (AAID) from it](https://developer.android.com/google/play-services/id.html).
2. Prepare the pixel URL for the HTTP request using the template:`https://pixel.mathtag.com/event/mob?mt_adid=ADVERTISER_ID&mt_id=PIXEL_ID&mt_uuid=AAID&mt_idt=aaid&ADDITIONAL_PARAMETERS`
3. Send the HTTP request by instantiating a hidden WebView (not Intent). [JavaScript must be enabled in the WebView.](http://developer.android.com/reference/android/webkit/WebSettings.html#setJavaScriptEnabled(boolean))


To fire additional pixels with other pixel IDs, repeat steps 2 and 3 above, updating the `PIXEL_ID` and `ADDITIONAL_PARAMETERS` in the URL as necessary.

## Native Android Example


```java
import com.google.android.gms.ads.identifier.AdvertisingIdClient;

AdvertisingIdClient.Info adInfo = null;
String my_AAID = null;
try {
  adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context);
  // Check for "Limit Ad Tracking".
  if (adInfo.isLimitAdTrackingEnabled()){
    //If LimitTrackingEnabled use a random UUID.
    my_AAID = UUID.randomUUID().toString();
  }
  // use the AAID .
  my_AAID = adInfo.getId();
}
catch (Exception e) {
  // Handle exception if any.
}
```

# Native implementation on Windows and Windows Phone

To manually fire a MathTag pixel on Windows or Windows Phone devices, follow these steps in your app’s code:

1. Request the `ADVERTISING_ID` from the [`Windows.System.UserProfile.AdvertisingManager` class](https://msdn.microsoft.com/en-us/library/windows/apps/windows.system.userprofile.advertisingmanager.advertisingid).
2. Prepare the pixel URL for the HTTP request using the following template: `https://pixel.mathtag.com/event/mob?mt_adid=ADVERTISER_ID&mt_id=PIXEL_ID&mt_uuid=ADVERTISING_ID&mt_idt=waid&ADDITIONAL_PARAMETERS`
3. Instantiate a hidden [WebView](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.controls.webview.aspx) control in your app and [set its URL to the URL generated in step 2](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.controls.webview.navigate.aspx).


# Implementing a Pixel for tracking app installs

One common use case for pixels in mobile apps is to track app installations (for example, to attribute conversions from a mobile ad campaign or from a promotion on a mobile site). This can be accomplished using either the SDK or Native methods described above.

**Important:** To gather accurate statistics about app installations, your app installation pixel should only fire the first time your app is run after installation.

To track app installations using TerminalOne pixels, you can do the following:

1. Have your marketing team create an event pixel in TerminalOne specifically for tracking app installations, and get the `PIXEL_ID` for that pixel.
2. If you're using the SDK, integrate it into your app as described in the above "Implementation using the MathTag Mobile SDK" section. If you're not using the SDK, ensure that the prerequisites in the "Native Implementation" section for your platform are met.
3. In the code that runs when your app is launched, add a function that does the following:
  1. Check for a key called "`installPixelFired`" in your application's preference store.
  2. If the key doesn't exist, execute a pixel fire as described above, using the installation-specific `PIXEL_ID` provided by your marketing team.
  3. Set the "`installPixelFired`" key in your application's preference store, to prevent this code from running on subsequent app launches.


The following Stack Overflow threads show examples of how to execute a function at first run and set a preference to track this:

- [Detecting first run on iOS](http://stackoverflow.com/a/9964400)
- [Detecting first run on Android](http://stackoverflow.com/a/12765731)


# Generating SHA 256 Hashes for Deterministic Reinforcement

## Android


```java
digest = MessageDigest.getInstance("SHA-256");
```

[http://stackoverflow.com/questions/7166129/how-can-i-calculate-the-sha-256-hash-of-a-string-in-android](http://stackoverflow.com/questions/7166129/how-can-i-calculate-the-sha-256-hash-of-a-string-in-android)

[https://developer.android.com/reference/java/security/MessageDigest.html](https://developer.android.com/reference/java/security/MessageDigest.html)

## iOS - Swift3


```objectivec
func sha256(data : Data) -&gt; Data {
  var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
  data.withUnsafeBytes {
    _ = CC_SHA256($0, CC_LONG(data.count), &amp;hash)
  }
  return Data(bytes: hash)
}
```

[http://stackoverflow.com/questions/25388747/sha256-in-swift](http://stackoverflow.com/questions/25388747/sha256-in-swift)

## iOS - ObjC


```objectivec
unsigned char hashedChars[32];
NSString *inputString;
inputString = [NSString stringWithFormat:@"hello"];
NSData * inputData = [inputString dataUsingEncoding:NSUTF8StringEncoding];
 CC_SHA256(inputData.bytes, inputData.length, hashedChars);
```

[http://stackoverflow.com/questions/3709204/sha256-in-objective-c-for-iphone](http://stackoverflow.com/questions/3709204/sha256-in-objective-c-for-iphone)

# Getting Support

If you have any questions about how to integrate pixels into your app, please [contact us](mailto:developers@mediamath.com).