This article will show you:

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

Overview

The Android SDK allows you to capture in-app referrals, and easily record any sales that occur on the back of these referrals within your Android 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 Android SDK

The Android 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 Android App 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;

• Your app must be optimised for Android 15+
• To support deep linking, your App should be configured for Android App 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?

Via Gradle

1. Add the following to your app/build.gradle file:

dependencies {
    // Partnerize App Tracking
    implementation 'com.partnerize.android:tracking:1.0'
}

2. You may also need to add the following to your project/build.gradle file:

buildscript {
    repositories {
        maven {
            url  "https://dl.bintray.com/performancehorizongroup/android"
        }
    }
}

Via manual AAR file

1. Download the latest SDK JAR file from https://dl.bintray.com/performancehorizongroup/android/com/partnerize/android/tracking/1.0/:tracking-<version>.aar

2. Import AAR file into project

Set required permissions

The AndroidManifest.xml should have the following permissions set:

<uses-permission android:name="android.permission.INTERNET" />

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.

The below snippet shows how the clickref can be obtained from the intent.

Intent intent = getIntent();
Conversion conversion = new Conversion(intent);

String clickRef = conversion.getClickRef();

❗NOTE: app_clickref 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.

2. Add sale information to the conversion

Now that a conversion has been created, you can now 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 snippet is an example of how you can create items and add them to the conversion;

// Create conversion item
ConversionItem item1 = new ConversionItem.Builder("9.99", "T-Shirt")
    .setQuantity(2)
    .setSku("TSH-PLN-MED")
    .build();

ConversionItem item2 = new ConversionItem.Builder("12.99", "Jeans")
    .setQuantity(1)
    .setSku("JEAN-BLK-32R")
    .build();

// Add the conversion items to the conversion
conversion = conversion.buildUpon()
    .setConversionItems({
        item1,
        item2
    })
    .build();

❗NOTE: value and category are required parameters of a conversion item, which represent the initial parameters of the conversion item builder.

This example will add the following items to the conversion;

• 2x T-Shirts with the SKU value of TSH-PLN-MED
• 1x Jeans with the SKU value of JEAN-BLK-32R

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;

conversion = conversion.buildUpon()
    .setVoucher("SALE10OFF")
    .build();

This will add the voucher of SALE10OFF to the conversion.

3. Complete conversion

When a checkout is made and payment has been received, the conversion can then be sent to Partnerize to record the sale.

The conversion object has a method toString() which returns the Partnerize conversion URL which can then be used by any HTTP client of your choice. See an example of this below utilising Okhttp;

// Convert the conversion into a Url
String url = conversion.toString();

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url(url)
  .build();

Response response = client.newCall(request).execute();

Additional information

Sandboxing

During development of your Android app you may need to sandbox the requests being made. The Conversion class has a toUrl method which allows the host and other aspects can be changed. For example:

// Additional metadata to indicate development mode (Optional)
conversion.addMetadata("development_mode", "yes");

Conversion.Url url = conversion.toUrl();

Conversion.Uri.Builder builder = url.buildUpon()
        .setScheme("http")
        .setAuthority("localhost");

String url = builder.toString();

Developer documentation

Additional documentation and further examples can be found on the Partnerize Android SDK Github page.