Performance Horizon's mobile measurement kit SDK allows advertisers to track installs and commissionable events and attribute to the original affiliate within a native application. By using the SDK in your app, in combination with the other components of Measurement Kit you can track a wide variety of in in-app events.
Measurement Kit consists of a tracking API, a smart banner SDK, and native SDK for iOS and Android. Building on top of Performance Horizon's API, Measurement Kit adds the additional facilities for interacting with native apps. Events and installs must be attributed to clicks either generated by the smart banner SDK, or by the mobile tracking API. Regular clicks (those from the domain prf.hn) are not tracked in all scenarios.
Integration with the mobile tracking API or the smart banner SDK is required for SDK install and event tracking.
This document describes installation and basic use of the mobile measurement kit SDK on the iOS platform.
Events and installs are tracked as conversions within the Performance Horizon Enterprise platform. At present, the conversions generated by MMK are of a type that is hidden within the standard interface. If you wish to view your events and installs, a conversion report can be generated by adding the conversion_meta_type=13 parameter to the conversion report, eg:
There are a number of options for integrating the iOS SDK into your project. The preferred method is via Cocoapods (see https://cocoapods.org/).
To install, add the following lines to your Podfile:
pod 'PHNMeasurementKit', '~> 0.4.6'
Then use the pod install command to download and install the library in your Xcode project.
The static library libPHNMeasurementKit-pod.a and it’s associated umbrella header PHNMeasurementKit.h can also be directly imported into an Xcode project. The library can be obtained by cloning the mobile tracking repository: https://github.com/PerformanceHorizonGroup/measurementkit-cocoapod.git
You'll need to be set up as a advertiser within Performance Horizon's affiliate tracking platform, with a campaign prepared. Please contact support for any further guidance.
MeasurementKit provides a singleton instance with a default configuration. If you wish to use a custom configuration, the instance must be initialised with a PHNMeasurementServiceConfiguration.
PHNMeasurementServiceConfiguration* configuration = [PHNMeasurementServiceConfiguration defaultConfiguration];
//Active fingerprinting uses webviews/safariviews for improved measurement accuracy.
config.activeFingerprint = YES;
PHNMeasurementService* measurement = [[PHNMeasurementService alloc] initWithConfiguration:configuration];
//set the shared instance for future use.
[PHNMeasurementService setSharedInstance:measurement];
Whether you're tracking installs, other events, or deep links, you'll need to initialise the SDK with your advertiser ID, and the campaign ID on which you want to track.
Import <PHNMeasurementKit/PHNMeasurementService.h> into your AppDelegate.m, and add the following
#import <PHNMeasurementKit/PHNMeasurementService.h>
- (void)applicationDidBecomeActive:(UIApplication *)application
{
NSString* phg_advertiser_id = @"advertiser_id";
NSString* phg_campaign_id = @"campaign_to_be_tracked";
[[PHNMeasurementService sharedInstance] startSessionWithAdvertiserID:phg_advertiser_id andCampaignID:phg_campaign_id];
}
You will receive your unique PHG Advertiser ID and Campaign ID when you are registered within the Performance Horizon platform.
To support iOS 8 and earler,
The measurement kit API appends an identifier to deep links. This identifier is used to initialise the SDK. Add the following to method to application:openURL:options: in your application delegate.
- (BOOL) application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options
{
// if you're processing the URI for routing in this method
// and you'd prefer the mobile tracking API additions removed,
// the output of this method is the original URI.
NSURL* originalurl = [[PHNMeasurementService sharedInstance] processDeepLinkWithURL:url];
/*
* Handle the deep link
*/
return YES;
}
From iOS 9 onwards, universal links are used to initialise measurement kit. Typically, a universal link is configured from the measurementkit API. Add the following to method to application:continueUserActivity:restorationHandler: in your application delegate.
- (BOOL) application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
{
NSURL* originalurl = [[PHNMeasurementService sharedInstance] processDeepLinkWithURL:userActivity.webpageURL];
return YES;
}
In addition, you will need to configure your app to support universal links. Please see: https://drive.google.com/file/d/0B3-jrdC-fCS4T3BueVE2T3ZUV00/view?usp=sharing
To support a deep-linking flow, a camref can be used to initialise a smart banner (see the Smart Banner SDK), or a universal link. To append camref to the destination url for a given campaign, in the Performance Horizon affiliate programme interface:
- With the campaign selected, select Admin -> Campaign from the navigation bar.
- In the campaign settings table, add
phn_camref=__CAMREF__to theAppend URL parametersfield.
A static instance of the measurement service is provided for convenience.
[PHNMeasurementService sharedInstance];
You can use events to track a variety of actions within your app. Events are represented as conversions inside the affiliate interface.
The most basic form of event has no value associated with it. (Perhaps an in-app action on which you're not looking to reward affiliates.)
The category parameter is used to set the product conversions.
PHNEvent* event = [[PHNMeasurementService sharedInstance] trackEvent:[PHNEvent eventWithCategory:@"registration-initiated"]];
If an event has a value you'd like to track, sales can be associated with an event as follows.
The currency parameter is a ISO 4217 currency code. (eg, USD, GBP)
//an example event with a single sale attached.
PHNSale* sale = [PHNSale saleWithCategory:@"registration-complete" andValue:[NSDecimalNumber decimalNumberWithString:@"1.10"];
PHNEvent *registration = [PHNEvent eventWithSale:sale ofCurrency:@"USD"];
[[PHNMeasurementService sharedInstance] trackEvent:registration];
//now one with several.....
PHNSale* upgrade= [PHNSale saleWithCategory:@"premium-upgrade" andValue:[NSDecimalNumber decimalNumberWithString:@"10.99"];
PHNSale* purchase = [PHNSale saleWithCategory:@"song-purchase" value:[NSDecimalNumber decimalNumberWithString:@"0.99"] sku:@"biffyclyro-12" andQuantity:1];
PHNEvent *purchases = [PHNEvent eventWithSales:@[upgrade, purchase] ofCurrency:@"USD"];
[[PHNMeasurementService sharedInstance] trackEvent:purchases];
sku and quantity are optional sales parameters.
MeasurementKit checks for affiliate activity on first launch. If there's no prior activity, it will be disabled for future launches. If you're testing an integration, you may wish to reset it so that it will check for affiliate activity on each launch. You can do this with the clearMeasurementServiceIDs method on MeasurementService.
NSString* phg_advertiser_id = @"advertiser_id";
NSString* phg_campaign_id = @"campaign_to_be_tracked";
[[PHNMeasurementService sharedInstance] clearMeasurementServiceIDs];
[[PHNMeasurementService sharedInstance] startSessionWithAdvertiserID:phg_advertiser_id andCampaignID:phg_campaign_id];
Measurement Kit is compatable with Swift, please ensure you add use_frameworks! in your podfile.
use_frameworks!
target 'Exactview' do
pod 'PHNMeasurementKit', '~> 0.4.6'
end
All MeasurementKit methods are then available in Swift, e.g:
PHNMeasurementService.sharedInstance().trackEvent(PHNEvent(category: "Signup"));
Advertiser and Campaign ID can both be found in the Settings section of the Performance Horizon web interface. See Admin -> Advertiser -> Advertiser ID.
Measurement Kit has a configuration option for extended debug logging that can be helpful in diagnosing integration issues. To enable, use the debugLoggingActive property on PHNMeasurementServiceConfiguration.
PHNMeasurementServiceConfiguration* configuration = [PHNMeasurementServiceConfiguration defaultConfiguration];
//enable debug logging.
configuration.debugLoggingActive = YES;
PHNMeasurementService* measurement = [[PHNMeasurementService alloc] initWithConfiguration:configuration];
//set the shared instance for future use.
[PHNMeasurementService setSharedInstance:measurement];