SDK Integration on
Android

SDK Integration

This guide walks you through how to add Button's SDK to your Android application. In this guide, we'll:

  1. Add the Button SDK
  2. Configure User Attribution
  3. Create a Button Purchase Path
  4. Add Impression Tracking

Add the Button SDK

Add the Button SDK to your build.gradle file in the dependencies.

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

Import and configure the SDK in your Activity. This should be called when your application class is created.

import com.usebutton.sdk.Button

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

    // Debugging enabled (do not include in production)
    if (BuildConfig.DEBUG) {
      Button.debug().loggingEnabled = 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 MyApplication 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 (minifyEnabled true in your build.gradle) make sure that the proguard rules below are in effect in your rules file. 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).

-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

Note: Passing a User ID is required for Loyalty Publishers.

Passing a user ID ensures subsequent Merchant activity (such as installs or purchases) is attributed to a user. This can either be their user ID or SHA-256 encoded email address. Never send personally identifiable information (PII) as the identifier. You can use this later to look up orders, activity and identify the user in Webhooks. String with a maximum length of 255.

Set the user ID in your login handler.

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

If your app offers logout functionality, invoke the SDK's logout feature during your logout handler.

Button.clearAllData()
Button.clearAllData();

Create a Button Purchase Path

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

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

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

    // Step 3 - Start Purchase Path flow
    purchasePath?.start(context)
}
// Step 1 - Create a Purchase Path request
String url = "https://www.example.com/";
PurchasePathRequest request = new PurchasePathRequest(url);

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

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

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

If Button can exchange the 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 merchant app, install flow, or web checkout.

You can pass an optional Publisher Reference (pubRef) (string with a maximum length of 512), which will be passed back to you in webhooks as pub_ref. This pass through value is typically used for click IDs, campaign IDs, etc.


Add Impression Tracking

While you'll be able to track taps and deeplinks in the Button Dashboard after each Purchase Path you start, in order to see the viewable impressions related to those taps, you'll need to implement Impression Tracking.

Button's impression tracking works by adding an ImpressionView as a subview to the views that you use to display offers to your users. Impression views are transparent and do not accept user interaction. They are used strictly to detect the visibility of the offer and track "viewable impressions" as users interact with your app.

This feature will be tracking what are known as “viewable impressions” as defined by the Interactive Advertising Bureau (IAB), where a viewable impression is one that meets the following criteria:

  • Pixel Requirement: Greater than or equal to 50% of the pixels (Density- Independent) in the offer were on an in-focus browser or a fully downloaded, opened, initialized application, on the viewable space of the device.
  • Time Requirement: The time the pixel requirement is met was greater than or equal to one continuous second, post offer render. The clock starts once the pixel requirement is met.
  • User Interaction: A strong user interaction with the offer can substitute the above requirements (i.e. a tap on the offer).

Adding Impression Views

Impression tracking illustration

You add impression views to your app's offer views just as you would add any other view. You can add them with a few lines of code in a layout file.

When you create an impression view, you specify a "creative type" to indicate where in your app an impression originated. The ImpressionView class exposes creativeType as an enumerated type in code, but it can be specified as a string in your layout or in Interface Builder.

Available Creative Types

  • hero
  • carousel
  • list
  • grid
  • detail
  • other

In View Layout

Add the impression view to your view layout with layout_width and layout_height set to match_parent.

<RelativeLayout
  xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="100dp">

  <!-- all your other view setup -->

  <com.usebutton.sdk.impression.ImpressionView
      android:id="@+id/color_impression_view"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      app:btn_creativeType="hero"
      />

</RelativeLayout>

Programmatically

val contentLayout : LinearLayout = ...

val impressionView = ImpressionView(context)
impressionView.creativeType = HERO
contentLayout.addView(impressionView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
LinearLayout contentLayout = ...;

ImpressionView impressionView = new ImpressionView(getContext());
impressionView.setCreativeType(HERO);
contentLayout.addView(impressionView, new LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT));

Tracking Offer Details

When you populate your offer views with data you’re displaying to the user, call track(…) on the ImpressionView that you added to that view in the previous step.

The track(…) method takes the following arguments:

  • url (string): The same URL you’ll use when fetching a Purchase Path from the Button SDK.
  • visibleRateType (enum): the rate type displayed to your user. Accepted values are "percent" or "fixed".
  • visibleRate (double): the visible rate displayed to your user, e.g. "5" to represent an offer of 5%.
  • offerId (string): If you’re using Button’s Personalized Rates API, the offers[].id associated with the offer. In the case of a Merchant with multiple categories/rates, please use the best_offer_id value. If you are not using the Rates API, do not include this value in the track(…) method.
// Track the new data on the associated ImpressionView
myOfferView.impressionView.track("https://example.com", // The URL for the Merchant offer
                                 PERCENT, // or FIXED (a percentage or fixed rate offer)
                                 5, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
                                 "offer-abc123def456abc1") // Only relevant if using Button's Personalized Rates API. If not, pass `null` here.
// Track the new data on the associated ImpressionView
myOfferView.impressionView.track("https://example.com", // The URL for the Merchant offer
                                 VisibleRateType.PERCENT, // or VisibleRateType.FIXED (a percentage or fixed rate offer)
                                 5, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
                                 "offer-abc123def456abc1"); // Only relevant if using Button's Personalized Rates API. If not, pass `null` here.