Postback Android SDK

Lightweight mobile attribution SDK for Android. Tracks installs, events, and campaign attribution with offline support.

Installation

Gradle (Maven Central)

Add to your app's build.gradle.kts:

dependencies {
    implementation("sh.postback:sdk:2.0.1")
}

Make sure mavenCentral() is in your repositories:

repositories {
    mavenCentral()
}

The SDK already declares INTERNET, ACCESS_NETWORK_STATE, and com.google.android.gms.permission.AD_ID, so you do not need to add them to your manifest.

Manual AAR

Download the AAR from Releases and add to your project's libs/ directory:

dependencies {
    implementation(files("libs/postback-sdk.aar"))
    implementation("androidx.lifecycle:lifecycle-process:2.10.0")
    implementation("com.google.android.gms:play-services-ads-identifier:18.3.0")
    implementation("com.android.installreferrer:installreferrer:2.2")
}

Quick Start

import sh.postback.sdk.Postback
import sh.postback.sdk.PostbackConfig
import sh.postback.sdk.PostbackEventType

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val sdk = Postback.shared(applicationContext)
        sdk.configure(PostbackConfig(apiKey = "pb_live_your_api_key"))

        sdk.sendEvent(
            PostbackEventType.PURCHASE,
            name = "premium_upgrade",
            params = mapOf("revenue" to 9.99, "currency" to "USD")
        )

        val attribution = sdk.getAttribution()
        println("Source: ${attribution?.source}")
    }
}

Configuration

val config = PostbackConfig(
    apiKey = "pb_live_...",                  // Required
    apiUrl = "https://api.postback.sh",    // Default
    customerUserId = null,                   // Optional: your internal user ID
    autoTrackSessions = true,                // Default: fires session_start on
                                             // configure() and foreground,
                                             // debounced to 30 min.
    autoRefreshAttribution = true,           // Default: refreshes attribution
                                             // on configure() and foreground.
    isDebug = false,                         // Default
    logLevel = 2                             // 0=debug, 1=info, 2=warn, 3=error
)

API Reference

val sdk = Postback.shared(context)

// Lifecycle
sdk.configure(config: PostbackConfig)
sdk.destroy()
sdk.isInitialized(): Boolean

// Events
sdk.sendEvent(type: PostbackEventType, name: String?, params: Map?)
sdk.sendTestEvent(): TestEventResult
sdk.flush()

// Attribution
sdk.getAttribution(): AttributionResult?
sdk.getAttributionParams(): Map<String, String>
sdk.getPostbackId(): String?
sdk.refreshAttribution(): AttributionResult?
// User
sdk.setCustomerUserId(userId: String)

// State
sdk.isSdkDisabled(): Boolean
sdk.clearData()

Event Types

SESSION_START, LOGIN, SIGN_UP, REGISTER, PURCHASE, SUBSCRIBE, START_TRIAL, ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, INITIATE_CHECKOUT, VIEW_CONTENT, VIEW_ITEM, SEARCH, SHARE, TUTORIAL_COMPLETE, ACHIEVE_LEVEL, LEVEL_START, LEVEL_COMPLETE, CUSTOM

Event Validation (1.0.1+)

• Custom events require a name. The SDK trims leading and trailing whitespace, then requires 1 through 255 UTF-16 code units and rejects names containing a NUL (U+0000) character. Invalid custom events are not queued or sent.
• Names on built-in events are optional. The SDK trims a valid name and omits an invalid one while still sending the event.
• currency is optional. When present, it is trimmed, must contain exactly three ASCII letters (A-Z or a-z), and is normalized to uppercase. An invalid currency is omitted while the event is still sent.
• Events queued by an older SDK are normalized when they flush. Invalid legacy custom events are dropped; invalid legacy names and currencies on otherwise valid events are omitted.

Privacy

The SDK reads the Google Advertising ID during install registration only, off the main thread. It honors Limit Ad Tracking and drops the all-zero advertising ID, so a bogus value never reaches the backend. Play Install Referrer is collected automatically for Play Store installs.

If you ship this SDK in a published app, include these in your Play Console Data safety answers:

• Advertising ID (collected, used for app functionality and advertising or marketing)
• Device or other IDs (the SDK-generated postbackId; Android has no IDFV equivalent)
• Approximate location and network-derived attributes (country/region derived by the backend from request metadata, plus connection type and carrier metadata where available)
• App activity (event names, parameters, revenue, currency)
• User ID, if you call setCustomerUserId()

If your app cannot collect advertising IDs (children's apps, certain regional policies), remove the permission in your host app manifest:

<manifest xmlns:tools="http://schemas.android.com/tools" ...>
    <uses-permission
        android:name="com.google.android.gms.permission.AD_ID"
        tools:node="remove" />
</manifest>

Don't pass raw user PII (email, phone, full name) through params or customerUserId. Both persist to SharedPreferences for retry durability. Use hashed or opaque identifiers (SHA-256 of an email, RevenueCat or Superwall app_user_id, your internal user UUID).

Requirements

• Android API 24+ (Android 7.0)
• Kotlin 1.9+ or Java 17

License

MIT License. See LICENSE for details.