Button Developers

Android App Setup

The Button Merchant Library for Android is a lightweight, open-source library designed to manage the Button Attribution Token. By the end of this section, you’ll be able to associate all incoming users against their subsequent taps in other applications that brought them to your Android application.

Add the Merchant Library

Include Dependency

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

implementation 'com.usebutton.merchant:button-merchant:1+'

Allow Gradle to download and include the Button Merchant Library before continuing.

Setup Library

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

import com.usebutton.sdk.ButtonMerchant

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

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

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

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

📘

Note

The Button Merchant Library is disabled by default. No user activity is reported and no data is collected until configured with an application id. Initialization can be deferred by simply not calling this method until ready to do so.

Additionally, some users will be initializing your application from a fresh install after following a promotion. In order to fulfill these specific user requests, include a call from within your application’s main Activity onCreate method to ButtonMerchant.handlePostInstallIntent. This will fetch the user’s intent prior to the fresh install, and route them directly to your relevant promotion. For more information on the handlePostInstallIntent method, take a look at Button Deferred Deeplinking.

import com.usebutton.sdk.ButtonMerchant

class MainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ButtonMerchant.handlePostInstallIntent(this) { intent, throwable ->
            // If Intent is available, start it
            intent?.let { startActivity(it) }
                                                      
            // Or if an error is provided, handle that
            throwable?.let { 
                Log.e("Button", "Error checking post install Intent", it)
            }
        }
    }
}
import com.usebutton.sdk.ButtonMerchant;
    
public class MainActivity extends Activity {
    @Override
    public void onCreate() {
        super.onCreate();

        ButtonMerchant.handlePostInstallIntent(this, new PostInstallIntentListener() {
            @Override
            public void onComplete(@Nullable Intent intent, @Nullable Throwable t) {
                if (intent != null) {
                    startActivity(intent);
                } else if (t != null) {
                    Log.e(TAG, "Error checking post install Intent", t);
                }
            }
        });
    }
}

Proguard Rules

If your app is using Proguard, make sure it includes rules for the Button Merchant Library. 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 Merchant Library

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

Register Deep Links

Button’s Merchant Library will abstract away any complexities of token management for you, including extracting the token from any incoming deeplinks.

For users that have already installed your application and are entering from another application’s promotion, pass the incoming URL to the Button Merchant Library in order to accurately attribute and handle their intent.

The ButtonMerchant class allows you to handle both Universal Linking and Custom Scheme URLs by passing the user intent to trackIncomingIntent.

This method should be called from the onCreate method in your launch Activity or whichever Activity handles incoming links. For example, if you use Verified App Links to directly open the product Activity, ButtonMerchant.trackIncomingIntent should be called from ProductActivity.onCreate.

import com.usebutton.sdk.ButtonMerchant

class ProductActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Handle custom scheme deeplinks and App Links
        ButtonMerchant.trackIncomingIntent(this, intent)
    }
}
import com.usebutton.sdk.ButtonMerchant;

public class ProductActivity extends Activity {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);

          // Handle custom scheme deeplinks and App Links
          ButtonMerchant.trackIncomingIntent(this, getIntent());
      }
}

Setup your Button Links domain

Once you’ve registered your Button Links subdomain (yourdomain.bttn.io), the last step is to add support for those links via intent filter within your Activity Declaration. If you’ve already registered an intent filter for your domain, you can simply add another to the same Activity Declaration.

We support verified web associated App Links so make sure to add the autoVerify="true" attribute to your intent filter.

🚧

Note

This support is part of Android Marshmallow (6.0), so you'll also need to build against this target Button Merchant Library level.

<activity name=".MainActivity">
        <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW"/>
                <data android:scheme="https"/>
                <data android:host="yourdomain.bttn.io"/>
                <data android:pathPattern=".*"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
        </intent-filter>
</activity>

Button hosts the Digital Asset Links JSON file for your bttn.io subdomain.

  • Once you have your updated Android Universal Link, navigate to the Button Dashboard Apps Section to add your certificate fingerprint.

  • Choose your Android application and click it's name to drill in.

  • Scroll down to the Configurations section and select Add Manual Configuration. If you've already added one, click Edit on the right side of that record.

  • You can add your package name and sha256 certificate fingerprints to your app configuration here.

Use the following command to generate the fingerprint via the Java keytool:

keytool -list -printcert -jarfile  <APK_FILE>  | grep SHA256

Now, your link should open your app without ever opening your browser when the app is installed.

📘

Note

By supporting web associated app links you will prevent the Intent Chooser when opening the URL and your app will open automatically.

Report Button Attribution Token

Once the user has placed an order in your app, include the Button Attribution Token before sending the user’s checkout request to your checkout API. The Button Attribution Token can be retrieved by calling the attributionToken method from the Button Merchant Library.

// Obtain Attribution Token
val btnRef = ButtonMerchant.getAttributionToken(context)
// Obtain Attribution Token
final String btnRef = ButtonMerchant.getAttributionToken(context);

Once the Button Attribution Token has been retrieved, include it in the order’s request parameters and execute a call to your checkout API as you normally would.

val url = URL("https://checkout-api.yourbrand.com")
val urlConnection = url.openConnection() as HttpURLConnection
urlConnection.doOutput = true

val json = JSONObject()
json.put("btn_ref", btnRef)
json.put("price", 34.90)
json.put("location", "New York")

val out = BufferedOutputStream(urlConnection.getOutputStream())
writeStream(out, json)
URL url = new URL("https://checkout-api.yourbrand.com");
HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
urlConnection.setDoOutput(true);

JSONObject json = new JSONObject();
json.put("btn_ref", btnRef);
json.put("price", 34.90);
json.put("location", "New York");

OutputStream out = new BufferedOutputStream(urlConnection.getOutputStream());
writeStream(out, json);

Report User Activity

You can report intermediate steps in the checkout funnel for analytics and measurement purposes, including:

  • Product Views
  • Add To Cart
  • Cart Views

This is achieved by first creating a Product, and then reporting it to the Merchant Library.

// Create product item
val product = ButtonProduct()
product.id = "abc123"
product.upc = "012345678901"
product.categories = listOf("Electronics", "Televisions")
product.name = "Flatscreen TV"
product.currency = "USD"
product.value = 39999
product.quantity = 1
product.url = "https://yourbrand.com/p/tv123"
product.attributes = mapOf("size" to "40 inch")

// Report a product view
ButtonMerchant.activity().productViewed(product)

// Report a product added to the cart
ButtonMerchant.activity().productAddedToCart(product)

// Report a cart view
ButtonMerchant.activity().cartViewed(productList)
// Create product item
ButtonProduct product = new ButtonProduct();
List<String> categories = new ArrayList<>();
categories.add("Electronics");
categories.add("Televisions");
Map<String, String> attributes = new HashMap<>();
attributes.put("size", "40 inch");
product.setId("abc123");
product.setUpc("012345678901");
product.setCategories(categories);
product.setName("Flatscreen TV");
product.setCurrency("USD");
product.setValue(39999);
product.setQuantity(1);
product.setUrl("https://yourbrand.com/p/tv123");
product.setAttributes(attributes);

// Report a product view
ButtonMerchant.activity().productViewed(product);

// Report a product added to the cart
ButtonMerchant.activity().productAddedToCart(product);

// Report a cart view
ButtonMerchant.activity().cartViewed(productList);

Note: You can pass your own product object by implementing the ButtonProductCompatible interface on your product class.

Updated about a month ago



Android App Setup


The Button Merchant Library for Android is a lightweight, open-source library designed to manage the Button Attribution Token. By the end of this section, you’ll be able to associate all incoming users against their subsequent taps in other applications that brought them to your Android application.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.