Introduction

The Android Mobile SDK allows you to capture in-app referrals, and easily record any sales that occur on the back of these referrals within your Android application.

The SDK provides two model classes; Conversion and ConversionItem. The Partnerize class is also used to provide functionality for dealing with inbound click for limitations on Android API 25+, the combination of these classes enables the following features within your Android app.

• Click reference retrieval from inbound requests to your Android app.
• Conversion creation with a range of attributes including custom metadata.
• Conversion item support for accurate shopping basket representation.
• Deep linking support for Web to App and App to App.

Quick Start

Installation

The Partnerize Mobile SDK for Android has been published as a maven package so the dependency can be included as a dependency in your app/build.gradle:

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

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

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

Handling inbound clicks

When an inbound intent from a mobile web browser or Android app launches your Android app via a deep link, a Conversion instance can be constructed from the intent, preserving the click reference.

In Android version 25 and over, links are no longer redirected from the browser, but instead handled directly in the Advertiser app. To handle this scenario, the SDK provides a beginConversion method to register the click with partnerize ready for conversion, as shown in the bellow snipped.

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        // inbound intent from partner app
        final Intent intent = getIntent();

        // uri -> https://example.prf.hn/click/camref:xxx/destination:https://example.domain.com/product/xxxx
        final Uri uri = intent.getData();

        Partnerize partnerize = new Partnerize(getApplicationContext());

        new Partnerize(this).beginConversion(uri, new CompletableVirtualClick() {
            @Override
            public void complete(VirtualClick click) {
                String destination = click.getDestination();
                String camRef = click.getCamRef();
                String clickRef = click.getClickRef();
                Map<String, String> utmParams = click.getUtmParams();
                Map<String, String> meta = click.getMetaParams();

                intent.setData(destination);
                // create outbound Intent to view the product and/or register Conversion
                Conversion conversion = new Conversion(intent, clickRef);
            }

            @Override
            public void error(PartnerizeException exception) {

            }
        });
    }

Alternatively, if just the destination URL is required, use the following method.

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    // inbound intent from partner app
    final Intent intent = getIntent();

    // uri -> https://example.prf.hn/click/camref:xxx/destination:https://example.domain.com/product/xxxx
    final Uri uri = intent.getData();

    Partnerize partnerize = new Partnerize(getApplicationContext());
    partnerize.beginConversion(uri, new CompletableClick() {
        @Override
        public void complete(Uri destination, String clickRef) {
            // destination -> https://example.domain.com/product/xxxx
            // clickRef -> xxxxxxxxxxxx

            intent.setData(destination);

            // create outbound Intent to view the product and/or register Conversion
            Conversion conversion = new Conversion(intent, clickRef);
        }

        @Override
        public void error(PartnerizeException exception) {
            // handle error
        }
    });
}

Partnerize also provides a getClickRef function to return the clickRef retrieved after beginConversion is called.

    Partnerize partnerize = new Partnerize(getApplicationContext());
    partnerize.getClickRef(); // -> xxxxxxxxxxxx

Posting Conversions to Partnerize

Once a conversion has been constructed and is ready to be recorded, it be can be sent to Partnerize using any HTTP request library. The Conversion class has a toString method which returns the URL which can be passed to a HTTP library like Volley or OkHttp.

Here’s a snippet that shows send a conversion to Partnerize via Volley

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

RequestQueue queue = Volley.newRequestQueue(this);

StringRequest request = new StringRequest(Request.Method.GET, url,
            new Response.Listener<String>() {
    @Override
    public void onResponse(String response) {
        // Successful
    }
}, new Response.ErrorListener() {
    @Override
    public void onErrorResponse(VolleyError error) {
        // Handle Error
    }
});

queue.add(request);

or alternatively with 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();

Since the Conversion.Builder class also has a toString method, a URL can be constructed without the Conversion being returned.

String url = new Conversion.Builder("my_click_reference").toString();

Resources

Click

The Click class describes attributes and items within a click. This is accessed with a Virtual Click Handler when calling Partnerize.beginConversion.

    String destination = click.getDestination();
    String camRef = click.getCamRef();
    String clickRef = click.getClickRef();
    Map<String, String> utmParams = click.getUtmParams();
    Map<String, String> meta = click.getMetaParams();

Conversion

The Conversion class describes attributes and items within a conversion.

The following code example demonstrates how to build a Conversion using the Conversion.Builder.

Conversion conversion = new Conversion.Builder("My_Click_Reference")
        .setConversionRef("my_conversion_reference")
        .setPublisherRef("my_publisher_reference")
        .setAdvertiserRef("my_advertiser_reference")
        .setCustomerRef("my_customer_reference")
        .setCurrency("USD")
        .setCountry("US")
        .setVoucher("25OFF")
        .setTrafficSource(TrafficSource.PARTNER)
        .setCustomerType(CustomerType.EXISTING)
        .setConversionMetric(ConversionMetric.STANDARD)
        // Conversion Metadata
        .addMetadata("payment_type", "crypto_currency")

        // Conversion Items
        .addConversionItem(new ConversionItem.Builder("52.99", "Shoes").build())
        .addConversionItem(new ConversionItem.Builder("84.98", "Shoes")
                .setSku("SHO-BLK-17")
                .setQuantity(2)
                .addMetadata("clearance", "true")
                .build())
        .build();

TrafficSource

The TrafficSource constants such as TrafficSource.PARTNER are for used for setting the traffic source on a conversion. Raw strings can also be used however, the Partnerize platform only accepts a predefined list of traffic sources.

CustomerType

This enum can either be CustomerType.EXISTING or CustomerType.NEW, and is used for setting the customer type on a conversion.

ConversionMetric

The ConversionMetric constants such as ConversionMetric.STANDARD are for used for setting the conversion metric on a conversion.

Retrieving and extending conversions

With a built Conversion instance each attribute can be retrieved by utilizing the get methods.

String clickRef = conversion.getClickRef();
String conversionRef = conversion.getConversionRef();
String publisherRef = conversion.getPublisherRef();
String advertiserRef = conversion.getAdvertiserRef();
String customerRef = conversion.getCustomerRef();
String currency = conversion.getCurrency();
String country = conversion.getCountry();
String voucher = conversion.getVoucher();
String trafficSource = conversion.getTrafficSource();

// Payment type metadata
String paymentType = conversion.getMetadata().get("payment_type");

// Second conversion item's quantity
int quantity = conversion.getConversionItems()[1].getQuantity();

Each Conversion is immutable which means when a Conversion has been constructed, it's attributes and ConversionItems cannot be modified, however the buildUpon method initiates a Conversion.Builder with the attributes and ConversionItems from the Conversion.

conversion = conversion.buildUpon()
        .setCustomerRef("other_customer_ref")
        .setVoucher("50OFF")

        // Conversion Metadata
        .addMetadata("guest", "false")

        // Conversion Item
        .addConversionItem(new ConversionItem.Builder("9.99", "Accessories")
                .build())
        .build();

ConversionItem

The ConversionItem class is a representation of an item within a Conversion to better represent a shopping basket.

A ConversionItem requires a value and category for each item however additional attributes can be associated; quantity, sku as well as custom metadata similar to conversions.

Using the following example shopping basket;

Name	Quantity	Price	SKU
Plain T-Shirt	3	9.99	TSH-PLN-MED
Coloured Vest	2	5.00	VES-COL-SMA
Sports Trainers	1	19.99	TRA-SPT-FIV
Coat	1	52.49	COA-TAN-LRG

It could be represented by the below conversion items:

ConversionItem conversionItem1 = new ConversionItem.Builder("9.99", "Tops")
        .setQuantity(1)
        .setSku("TSH-PLN-MED")
        .build();

ConversionItem conversionItem2 = new ConversionItem.Builder("5.00", "Tops")
        .setQuantity(2)
        .setSku("VES-COL-SMA")
        .addMetadata("clearance", "yes")
        .build();

ConversionItem conversionItem3 = new ConversionItem.Builder("19.99", "Shoes")
        .setQuantity(1)
        .setSku("TRA-SPT-FIV")
        .build();

ConversionItem conversionItem4 = new ConversionItem.Builder("52.49", "Coats")
        .setQuantity(1)
        .setSku("COA-TAN-LRG")
        .addMetadata("season", "winter")
        .build();

// Add the conversion items to the conversion
conversion = conversion.buildUpon()
    .setConversionItems({
        conversionItem1,
        conversionItem2,
        conversionItem3,
        conversionItem4
    })
    .build();

Modifying and removing conversion items

Similar to Conversion, ConversionItems are also immutable, therefore in order to modify them they must be fed into a ConversionItem.Builder using the buildUpon method.

When utilizing the buildUpon method for ConversionItems, the newly built instance does not get added onto the Conversion, this is because the ConversionItem.Builder returns a new ConversionItem. This approach leads to more readable code without any assumptions being made on the state of the Conversion.

Here’s an example that shows how a ConversionItem can be removed, modified and added onto the Conversion.

// Retrieve the ConversionItem being modified
ConversionItem conversionItem = conversion.getConversionItems()[0];

conversion = conversion.buildUpon()
        .removeConversionItem(conversionItem)
        .addConversionItem(conversionItem.buildUpon()
            .setQuantity(3)
            .build())
        .build();

Storing the click reference

Within your Android app you may have a user flow which spans over multi screens, meaning that the click reference needs to be persisted between activities.

Conversion instances implement the Android Parcelable interface, this allows the Conversion to be serialized by the Android platform and passed between activities within your Android app.

Here’s a snippet that shows how a Conversion can be passed to another activity

Intent intent = new Intent(this, NextActivity.class);
intent.putExtra("conversion", conversion);

startActivity(intent);

And retrieving the Conversion from the subsequent activity.

Conversion conversion = getIntent().getExtras().getParcelable("conversion");

Persistent click reference storage

Since the click reference is stored as a String it can be stored using Android String storage mechanics, should the need arise that the click reference needs to persist more permanently.

Here’s a snippet that shows how a click reference can be stored by SharedPerferences

SharedPreferences preferences = PreferenceManager.getDefaultSharedPreferences(context);
SharedPreferences.Editor editor = preferences.edit();

// Put the click reference within SharedPreferences
editor.putString("clickRef", conversion.getClickRef());

editor.apply();
editor.commit();

Partnerize also provides a getClickRef function to return the clickRef retreived after beginConversion is called.

    Partnerize partnerize = new Partnerize(getApplicationContext());
    partnerize.getClickRef(); // -> xxxxxxxxxxxx

Development mode

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();

License

Apache-2.0

Release Notes

Release notes can be found here