Android App Setup
In this section we will walk through the steps needed to integrate your Android application with Button.
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:6+'
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().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 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.
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 Personalization 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.
Report Impression Views
It is critical to implement Impression Views within your app UI. Without this data, your integration will have an incomplete view of the user behavior funnel.
Impression views are programmatically wrapped subviews around your offer views which enable viewable impressions. In specific, they meet 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.
The implementation can be done in code or statically in a View layout.
If you’re writing code, utilize Button’s ImpressionView
class and supply a string value to the exposed enumerated creativeType
. The available creativeType
values are: hero
, carousel
, list
, grid
, detail
, other
.
The following example shows how an Impression View is added to an Offer View.
// Retrieve reference to the container layout
val contentLayout : LinearLayout = ...
// Create and ImpressionView and specify the type
val impressionView = ImpressionView(context)
impressionView.creativeType = CreativeType.HERO
// Append the ImpressionView to the container view
contentLayout.addView(impressionView, LayoutParams(LayoutParams.MATCH_PARENT,
LayoutParams.MATCH_PARENT))
LinearLayout contentLayout = ...;
ImpressionView impressionView = new ImpressionView(getContext());
impressionView.setCreativeType(CreativeType.HERO);
contentLayout.addView(impressionView, new LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT));
If you’d like to implement an Impression View within an XML layout, make sure to set the ImpressionView
's dimension layout_width
and layout_height
to match_parent
.
<LinearLayout
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"
/>
</LinearLayout>
Next, it's time to ensure your Impression Views track data by calling the configureWith
method wherever your offer views are being recycled with new data. This is distinct from impression events, which are handled by Button when Impression Views are rendered.
To implement tracking, call the configureWith
method and supplying the following required arguments:
Property | Description | Property Type |
---|---|---|
url | The URL destination of the offer rendered. This is the same URL used when fetching a Purchase Path using the Button SDK | string |
visibleRateType | The rate type displayed to your user. Valid options are percent or fixed | enum |
visibleRate | The visible rate displayed to your user. For example a value of 5 represents an offer shown to the user of 5% | double |
offerId | This is the id associated with the offer fetched from the Button Personalization API. | string |
Remember to always call configureWith
whenever your Offer Views are updated with new data, such as when making another fetch to the Button Personalization API, or when rendering new offers.
// Configure the Impression View with new offer details
val offerDetails = OfferDetails.Builder(
"https://example.com", // The URL for the Brand offer
"offer-abc123def456abc1", // The offer Id provided by the Button Personalization API
5f, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
VisibleRateType.PERCENT // or FIXED (a percentage or fixed rate offer)
).build()
myOfferView.impressionView.configureWith(offerDetails)
// Configure the Impression View with new offer details
OfferDetails offerDetails = new OfferDetails.Builder(
"https://example.com", // The URL for the Brand offer
"offer-abc123def456abc1", // The offer Id provided by the Button Personalization API
5, // The rate visible to the user on your offer view. In this example, it's a 5% offer.
VisibleRateType.PERCENT // or FIXED (a percentage or fixed rate offer)
).build();
myOfferView.impressionView.configureWith(offerDetails);
Debugging Impression Tracking
In order to help debug Impression Tracking, the Button SDK supports an impression tracking debugging mode that will show you viewable areas for impression tracking views and log helpful messages to the debug console.
Button.debug().isVisualDebuggingEnabled = true
Button.debug().setVisualDebuggingEnabled(true);
For more information, take a look at the Debugging Impression Tracking guide
Updated 8 months ago