Android App Setup

Add the Button SDK to your Android application

To get started, add the Button SDK to your build.gradle file in the dependencies.

    implementation 'com.usebutton:android-sdk:7+'

Next, import and configure the Button SDK in either the Application subclass (preferred), or the launching Activity.

import com.usebutton.sdk.Button

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

        // Debugging enabled (do not include in production)
        if (BuildConfig.DEBUG) {
					Button.debug().isLoggingEnabled = true
        }

        // Replace app-xxxxxxxxxxxxxxxx with your App ID from the
        // Button Dashboard: https://app.usebutton.com
        Button.configure(this, "app-xxxxxxxxxxxxxxxx")
    }
}

import com.usebutton.sdk.Button;

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Debugging enabled (do not include in production)
        if (BuildConfig.DEBUG) {
            Button.debug().setLoggingEnabled(true);
        }

        // Replace app-xxxxxxxxxxxxxxxx with your App ID from the
      	// Button Dashboard: https://app.usebutton.com
        Button.configure(this, "app-xxxxxxxxxxxxxxxx");
    }
}

Proguard Rules

If your app is using Proguard, make sure it includes rules for the Button SDK. This file is usually located in yourapp/proguard-rules.pro, or its location is specified in build.gradle, look for proguardFiles in your default or variant configuration (note: this can be multiple files).

Here is an example proguard-rules.pro snippet including the Button SDK:

-keepattributes Exceptions,InnerClasses,EnclosingMethod
-keep class com.usebutton.** { *; }
-keepclassmembers class * implements android.os.Parcelable {
    static ** CREATOR;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient { public *; }

Configure User Attribution

User attribution ensures downstream commerce activity is associated with a unique user identifier. We recommend anonymizing this identifier before reporting it to Button (e.g. providing a uuid for the user, or hashed email via sha-256). Once your user finalizes a purchase, we’ll notify you using this identifier. Note: This should be the same ID that is passed as the user_id when calling the Offers API.

Warning: Never send personally identifiable information (PII) as the identifier. If you’re unsure about this, please reach out to your Button representative who can help guide you to follow our security & privacy best practices.

After your Publisher application launches and has been configured with the Button SDK, you can configure user attribution. If a user is already logged in, you can pass your application’s User ID to the Button.user.setIdentifier method. This identifier must be a string between 1 and 255 characters long in the ASCII range [0x21-0x7E]. If a user has not yet logged in, handle your user’s login first before calling Button.user.setIdentifier.

Button.user().setIdentifier("YOUR_LOGGED_IN_USERS_ID")

Button.user().setIdentifier("YOUR_LOGGED_IN_USERS_ID");

Similarly, after your user has successfully logged out of your Publisher application, invoke the Button SDK’s logout feature by calling the Button.clearAllData method. This method only needs to be called once at the time of logout.

Button.clearAllData()

Button.clearAllData();

Handle Link Routing When A User Taps

Next, it’s time to handle link routing when a user taps on an offer. This is done by setting up a Button Purchase Path wherever your mobile application routes your user to a Brand.

Creating a Purchase Path is done by passing a Brand URL into the PurchasePathRequest. Upon passing the PurchasePathRequest into the Button.purchasePath.fetch method, the Button SDK will first validate that the PurchasePathRequest is valid. If it is, then the Button SDK will initialize the Purchase Path flow.

If Button can exchange the given URL for a fully attributed action, the fetch will complete with a PurchasePath. Starting a purchasePath will pass control to the Button SDK which will open the Brand app, install flow, or web checkout.

Publishers should pass the value returned by the Offers API in the offer_id field as the offerId when creating Purchase Path requests.

In order to help with tracking this Purchase Path, Publishers can optionally set a value to the PurchasePathRequest's pubRef property. The pubRef (Publisher Reference) accepts a string value with a maximum length of 512, and is made available downstream in Button Webhooks as pub_ref . Publishers usually populate this value with click IDs, campaign IDs, and other identifiers to help with measuring performance.

// Step 1 - Create a Purchase Path request
val url = "https://www.example.com/"
val request = PurchasePathRequest(url)

// Step 2 - Associate the offerId
request.offerId = "offer-G123456789123_abcdefghijklmnopqrstuvwxyzABCDEFGFHIJKL"

// Optionally associate a unique token (e.g. campaign Id)
// request.pubRef = "abc123"

// Step 3 - Fetch a Purchase Path object
Button.purchasePath().fetch(request) { purchasePath, throwable ->

    // Step 4 - Start Purchase Path flow
    // (Note: for CLO integrations this step is skipped)
    purchasePath?.start(context)
}

// Step 1 - Create a Purchase Path request
String url = "https://www.example.com/";
PurchasePathRequest request = new PurchasePathRequest(url);

// Step 2 - Associate the offerId
request.setOfferId("offer-G123456789123_abcdefghijklmnopqrstuvwxyzABCDEFGFHIJKL");

// Optionally associate a unique token (e.g. campaign Id)
// request.setPubRef("abc-123");

// Step 3 - Fetch a Purchase Path object
Button.purchasePath().fetch(request, new PurchasePathListener() {
    @Override
    public void onComplete(@Nullable PurchasePath purchasePath,
            @Nullable Throwable throwable) {

        // Step 4 - Start Purchase Path flow
        if (purchasePath != null) {
            purchasePath.start(context);
        }
    }
});

Now that you’ve set up a Purchase Path, you’ll be able to track taps and deep links visited within the Button Dashboard.