Resource Center

Search

Mobile Tracking: iOS AllTrack SDK

This article will show you:

  • How to integrate the Partnerize iOS Mobile SDK within your application to capture clicks and record transactions from within your mobile application

 

Overview

The iOS SDK allows you to capture in-app referrals, and easily record any sales that occur on the back of these referrals within your iOS applications, bridging the gap between web and app based activity.

__________________________________________________________________________________________________________________

❗NOTE:Although out of scope of the SDK, documentation is also available on how you are able to ensure your referrals will be able to facilitate users on all journeys including Web to App, App to App and App to Web. For further information, contact your Customer Success manager.

____________________________________________________________________________________________________________________

Features of the iOS SDK

The iOS SDK provides you with the following functionality;

  • Click storing and matching
    Clicks can be easily detected coming into your app, and the click can be stored for use as and when a sale is made within the app.
  • Conversion instantiation
    Conversions can easily be instantiated of which will then have a multitude of different methods available in order to add information about the conversion as and when the user adds items into their basket and/or checkouts.
  • Custom conversion metadata
    Any top-level custom metadata that is relevant can easily be passed through with the conversion.
  • Conversion item support
    Any number of items with custom metadata can be attached to conversions to record true basket information of the sale.
  • Conversion recording
    When a conversion has been instantiated, a click has been assigned and information has been passed into it, it can then be recorded as a conversion directly with Partnerize.
  • Report Filtering
    Any conversion recorded as part of the SDK will be recorded in the Partnerize reporting suite as a sale from an App on a Mobile Device, enabling you to easily use filters to display these conversions within the Partnerize reporting tools.
  • Existing partner tracking links
    Existing partner tracking links are fully compatible and require zero migration efforts for partners.
  • Deep linking support
    Deep linking via Universal Links is fully supported and although is not direct functionality of the SDK, it is marked as a requirement which can be found below.

Can I use the SDK?

In order to install and begin utilising the SDK, the following conditions must be met;

  • You must be using Xcode 10.0 or higher
  • Your app must be optimised for iOS 9+
  • To support deep linking, your App should be configured for Apple Universal Links
  • You must be enabled for App Tracking.  If you are not already, then please contact your Customer Success Manager for assistance.

How do I Install the SDK?

Once you are ready to Install the SDK, it is recommended that this be done using an iOS package manager, due to the ease of integration and updates.  If, however, you wish to install manually, then a manual static framework installation is also made available for you to use.

Via iOS Package Manager

If you are installing the SDK via an iOS package manager, then follow these steps;

Using Cocoapods;

  1. Ensure you have the latest version of CocoaPods.
  2. Add the following to your Podfile
    pod 'Partnerize'
  3. Run pod install.
  4. Ensure the project is now always opened with the .xcworkspace file and not the .xcodeproj file.

Using Carthage;

  1. Ensure you have the latest version of Carthage.
  2. Add the following to your Cartfile:  github "PerformanceHorizonGroup/partnerize-mobile-sdk-ios"
  3. Run carthage update.
  4. Copy Partnerize.framework from Carthage/Build/iOS to the "Embedded Binaries" section in the General Settings of your Xcode project.
  5. After verifying your project compiles, switch over to Build Phases and add a new Run Script build phase by clicking the “+” in the top left of the editor and add the following command:
    /usr/local/bin/carthage copy-frameworks
  6. Click the + under Input Files and add an entry for Partnerize framework:
    $(SRCROOT)/Carthage/Build/iOS/Partnerize.framework

Via Manual Framework

If you wish to install the SDK manually, then you should follow these steps;

  1. Download the latest Partnerize iOS SDK as a ZIP file (Source code).
  2. Copy Partnerize.framework from the extracted ZIP file into to the "Embedded Binaries" section in the General Settings of your Xcode project.
  3. Create a new “Run Script Phase” in your application targets “Build Phases” and paste the following snippet in the script test field:
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Partnerize.framework/strip-frameworks.sh"

Using the SDK

Once you have installed the SDK, you can begin to use it to capture clicks and record any sales that occur in-app.

The most simple SDK usage consists of 3 simple steps;

  1. Capture Partnerize clicks and initiate a conversion
  2. Add sale information into the conversion
  3. Complete conversion

The below will provide further information on how to achieve this using the SDK and additional developer friendly documentation can also be found here.

1. Capturing clicks and initiating a conversion

All incoming Partnerize clicks will include a query string parameter as part of the URL called app_clickref* which is required in order to start a conversion.

*This will automatically be appended to every request when the "App Tracking" feature is enabled on your campaign and the request is initiated from a mobile device

Swift

func application(_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
...
if let url = try? Partnerize.beginConversion(with: userActivity.webpageURL) {
// Handle deep link code
}
...
}
Objective-C - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
…
NSError *error = nil;
NSURL *url = [Partnerize beginConversionWithURL:userActivity.webpageURL error:&error];

if (!error && url) {
// Handle deep link code
}

2. Add sale information to the conversion

Now that a conversion has been initialised on the back of a Partnerize click request, you can interact with the conversion at any time to add specific information relating to the sale, for example when a user adds an item into their basket or when they checkout.

The following code is an example of how you can create an item and add it to the conversion;

Swift let item = ConversionItem(value: "59.99", category: "Shoes", quantity: "5", metadata:["brand": "adidas", "model": "stan smith"])
let item2 = ConversionItem(value: "74.00", category: "Jeans", metadata:["brand": "levis"])

Partnerize.conversion?.items = [item, item2]
Objective-C

PHGConversionItem *item = [[PHGConversionItem alloc] initWithValue:@"59.99" category:@"Shoes" quantity:@"5" metadata:@{@"brand": @"adidas", @"model" : @"stan smith"}];

PHGConversionItem *item2 = [[PHGConversionItem alloc] initWithValue:@"74.00" category:@"Jeans" metadata:@{@"brand": @"levis"}];

Partnerize.conversion.items = @[item, item2];

*A conversion item required a value and a category as minimum required parameters

This example will add the following items to the conversion;

  • 5 pairs of Adidas Stan Smith shoes priced at 59.99
  • 1 pair of Levis jeans prices at 74.00

3. Complete conversion

Now that a conversion has items associated with it, it is now a valid sale and can be submitted at any time. You can still make changes if you wish to the conversion object itself, for example if you wish to apply a discount voucher, which can be done simply with;

Swift

Partnerize.conversion?.voucher = "SALE10OFF"
Objective-C

Partnerize.conversion.voucher = @"SALE10OFF";

This will add the voucher of SALE10OFF to the conversion.

When a checkout is made and payment has been received you can then complete the conversion which will then send the conversion to Partnerize and will be tracked.

Swift

Partnerize.completeConversion { success, error in
if success {
// handle success
}
else if let error = error {
// handle error, f.i. log it
}
}
Objective-C

[Partnerize completeConversionWithCompletionHandler:^(BOOL success, NSError * _Nullable error) {
if (success) {
// handle success
}
else if (error != nil) {
// handle error, f.i. log it
}
}];

Additional information

Override the Tracking Domain

By default, the tracking domain is set to https://prf.hn, which is the Partnerize production tracking domain.

Should there be a reason to override this value, for example if you wish to point your requests to the Partnerize demo tracking service, this can be updated in the PZ_SERVICE_URL setting in the Info.plist of the framework.

Optional logging

Some events that occur within the SDK will return various logging information to aid you in your development of the SDK.

Unified Logging and Tracing System

Swift Partnerize.isLoggingEnabled = true
Objective-C Partnerize.enableLogging = YES;

 

Was this article helpful?

2 out of 3 found this helpful

Have more questions? Submit a request