Introduction

The Partnerize Android Mobile SDK enables your app to capture in-app referrals and accurately attribute subsequent sales. It simplifies tracking across web-to-app and app-to-app flows, providing seamless integration for recording conversions.

Minimum Requirements

  • Android API level 26 (Oreo)
  • Gradle 8.7
  • Android Studio 2022.3 (or compatible with Gradle 8.7)
  • Java 17 or above / Kotlin 1.8

Installation

Add the Partnerize SDK

You can integrate the SDK using Maven (recommended) or manual .aar installation.

Add the dependency to your app-level build.gradle file.

Groovy

dependencies {
    implementation 'com.partnerize.android:tracking:3.0.1'
}

Kotlin

dependencies {
    implementation("com.partnerize.android:tracking:3.0.1")
}

Manual Installation (.aar)

Use this method if you're provided with the SDK as a .aar file.

Step 1: Add the file

Place the tracking-3.0.1.aar file in:

app/libs

Step 2: Update your Gradle configuration

// groovy DSL
repositories {
    flatDir {
        dirs "libs"
    }
}

dependencies {
    implementation(name: "tracking-3.0.1", ext: "aar")
}

// kotlin DSL
dependencies {
    implementation(files("libs/tracking-3.0.1.aar"))
}

Step 3: Resync the gradle project

Quick Start

Initialise the SDK

Create an instance per platform you need. You can keep both if you support both Partnerize and Ascend.

val sdkPartnerize = PartnerizeTracking.partnerize(applicationContext)
val sdkAscend = PartnerizeTracking.ascend(applicationContext, "your_ascend_api_key")

Handle Inbound Clicks

Process incoming tracking URLs and optionally persist the click reference for later conversions.

val attribution = sdkPartnerize.captureAttribution(
    url = inboundUri,
    persist = true // default; set false to avoid storing
)

If the URL is invalid or missing required parameters, a PartnerizeException is thrown. Returns:

  • Partnerize SDK: PartnerizeAttribution (clickref: String?)
  • Ascend SDK: AscendAttribution (clickId: String?, gClickId: String?) — if provided, clickId must be an integer; gClickId can be used on its own.

Attribution examples (what gets stored)

Example inbound URLs (replace host/path with your deep link handler):

  • Partnerize: https://example.com/deeplink?clickref=abc123
  • Ascend: myapp://open?click_id=42&gclick_id=g-1 or myapp://open?gclick_id=g-2

Partnerize (overwrites)

val sdkPartnerize = PartnerizeTracking.partnerize(applicationContext)
val uriWithClickRef = Uri.parse("https://example.com/deeplink?clickref=abc123")
sdkPartnerize.captureAttribution(uriWithClickRef, persist = true)
sdkPartnerize.getStoredAttribution().clickRef // "abc123"

// later inbound URL contains clickref=xyz999
val nextUri = Uri.parse("https://example.com/deeplink?clickref=xyz999")
sdkPartnerize.captureAttribution(nextUri, persist = true)
sdkPartnerize.getStoredAttribution().clickRef // "xyz999" (previous overwritten)

Ascend (appends)

val sdkAscend = PartnerizeTracking.ascend(applicationContext)

// inbound URL contains click_id=42&gclick_id=g-1
val uriA = Uri.parse("myapp://open?click_id=42&gclick_id=g-1")
sdkAscend.captureAttribution(uriA, persist = true)
sdkAscend.getStoredAttribution().clickIds  // [42]
sdkAscend.getStoredAttribution().gClickIds // ["g-1"]

// later inbound URL contains only gclick_id=g-2 (no click_id)
val uriB = Uri.parse("myapp://open?gclick_id=g-2")
sdkAscend.captureAttribution(uriB, persist = true)
sdkAscend.getStoredAttribution().clickIds  // [42]           (unchanged)
sdkAscend.getStoredAttribution().gClickIds // ["g-1", "g-2"] (appended)

Post Conversions

Create a platform-specific conversion object, then call completeConversion from a coroutine. Stored attribution is injected automatically; you can override it via alternateStoredAttribution.

lifecycleScope.launch {
    val result = sdkPartnerize.completeConversion(conversion)
    // result is PartnerizeConversionResult or AscendConversionResult depending on the SDK instance
}

Signature:

suspend fun completeConversion(
    conversion: Conversion,
    alternateStoredAttribution: StoredAttribution? = null,
): ConversionResult

Stored Attribution Utilities

  • getStoredAttribution(): returns the currently stored attribution (platform-specific type).
  • clearStoredAttribution(): removes any stored attribution.

Use these to inspect or reset attribution state between user sessions or logout flows. Storage behavior differs by platform (see platform sections below for overwrite vs append details).

Logging

Enable built-in logging or provide your own logger:

sdk.loggingEnabled = true

class MyLogger : PartnerizeLogger {
    override fun log(message: String) {
        println(message)
    }
}
sdk.logger = MyLogger()

Partnerize Platform

Initialise with:

val sdkPartnerize = PartnerizeTracking.partnerize(applicationContext)

Attribution

  • PartnerizeAttribution — returned by captureAttribution; fields: clickref: String?
  • PartnerizeStoredAttribution — returned by getStoredAttribution; fields: clickRef: String?
  • Storage behavior: calling captureAttribution with persist = true overwrites the stored clickRef with the newest valid inbound URL.

Build a Conversion

Use PartnerizeConversion.Builder() to configure a conversion. The SDK injects the stored clickRef automatically during completeConversion (or you can supply an alternate stored attribution).

val conversion = PartnerizeConversion.Builder()
    .setConversionRef("conv_001")
    .setCurrency("GBP")
    .setCountry("GB")
    .setCustomerType(CustomerType.NEW)
    .addMetadata("channel", "app")
    .addConversionItem(
        PartnerizeConversionItem.Builder("9.99", "Tops")
            .setQuantity(2)
            .setSku("SKU123")
            .build()
    )
    .build()

lifecycleScope.launch {
    val result: PartnerizeConversionResult = sdkPartnerize.completeConversion(conversion)
    val conversionId = result.conversionId
}

Builder

Start with PartnerizeConversion.Builder(), then chain:

  • setConversionRef(String?)
  • setPublisherRef(String?)
  • setAdvertiserRef(String?)
  • setCustomerRef(String?)
  • setCurrency(String?)
  • setCountry(String?)
  • setVoucher(String?)
  • setTrafficSource(String?)
  • setCustomerType(CustomerType?)
  • setConversionMetric(String?)
  • setFulfilmentDate(Date?)
  • setFulfilmentStartDate(Date?)
  • addMetadata(String, String)
  • removeMetadata(String)
  • setConversionItems(List<PartnerizeConversionItem>)
  • addConversionItem(PartnerizeConversionItem)
  • removeConversionItem(PartnerizeConversionItem)
  • build()
  • buildUpon()

Call build() when you are done configuring to produce the conversion. Use buildUpon() to clone an existing conversion and adjust fields without starting from scratch.

PartnerizeConversionItem

val item = PartnerizeConversionItem.Builder(value = "9.99", category = "Tops")
    .setQuantity(2)
    .setSku("SKU123")
    .addMetadata("color", "red")
    .build()

Required: value: String, category: String
Optional: quantity: Int, sku: String?, metadata

ConversionResult

Returns PartnerizeConversionResult with:

  • conversionId: String

Ascend Platform

Initialise with following (replace with your actual Ascend API key):

val sdkAscend = PartnerizeTracking.ascend(applicationContext, "your_ascend_api_key")

Your Ascend API key can be found https://www.ascendpartner.com/merchant/api/ dashboard under "API Keys" section. If no API key is available, SDK will throw an error when you try to initialise.

Attribution

  • AscendAttribution — returned by captureAttribution; fields: clickId: String?, gClickId: String?
  • AscendStoredAttribution — returned by getStoredAttribution; fields: clickIds: List<Int>, gClickIds: List<String>
  • Storage behavior: calling captureAttribution with persist = true appends new click IDs (if valid); multiple IDs are kept until you clear them via clearStoredAttribution() method.
  • clickId is optional, but when present it must be an integer; gClickId alone is accepted and stored.

Build a Conversion

Use AscendConversion.Builder(...) with the required constructor arguments shown below. Stored click IDs are injected by the SDK when posting the conversion.

val items = listOf(
    AscendConversionItem.Builder(
        id = "item_001",
        amount = 49.99,
        quantity = 1
    ).setCategory("Tops").build()
)

val conversion = AscendConversion.Builder(
    orderId = "order_001",
    items = items,
    created = "2024-01-01T12:00:00Z",
    currency = "GBP"
)
    .setPublisherId(1234)
    .setType(TransactionType.SALE)
    .setNewToFile(true)
    .setCoupons(listOf("WELCOME10"))
    .setSegment("vip")
    .build()

lifecycleScope.launch {
    val result: AscendConversionResult = sdkAscend.completeConversion(conversion)
    val message = result.message
}

Builder

Create the builder with required arguments:

  • orderId: String
  • items: List<AscendConversionItem>
  • created: String
  • currency: String

Then chain builder methods:

  • setPublisherId(Int)
  • setType(TransactionType)
  • setNewToFile(Boolean)
  • setCoupons(List<String>)
  • setSegment(String)
  • build()

Call build() when you are done configuring to produce the conversion.

AscendConversionItem

val item = AscendConversionItem.Builder(
    id = "item_001",
    amount = 49.99,
    quantity = 1
).setCategory("Tops").build()

Required: id: String, amount: Double, quantity: Int
Optional: category: String?

ConversionResult

Returns AscendConversionResult with:

  • message: String? (API response message)

License

Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0

Support

If you encounter any issues, email:

support@partnerize.com

Include:

  • Steps to reproduce
  • URLs used
  • Logger output
  • SDK version

Release Notes

Release notes can be found here