Button Merchant Library for Native Apps on
Android
iOS

Button Merchant Library for Native Apps


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 Button Merchant Library

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

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

In your launcher Activity or Application class file, import the Button Merchant Library at the top of your Activity and start it within the onCreate method.


    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(context, "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() {
        super.onCreate()
    
        ButtonMerchant.handlePostInstallIntent(this) { intent, t ->
                if (intent != null) {
                    startActivity(intent)
                } else if (t != null) {
                    Log.e(TAG, "Error checking post install intent", t)
                }
            }
        })
    
      }
    }


    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 *; }


Registering Deeplinks with Button’s Merchant Library

Button’s Merchant Library will abstract 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 whatever Activity handles incoming links. For example, if you use Verified App to directly open the product Activity, ButtonMerchant.trackIncomingIntent should be called from ProductActivity.onCreate.


    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    
        // Handle custom scheme deeplinks and App Links
        ButtonMerchant.trackIncomingIntent(this, intent)
    }


    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    
        // Handle custom scheme deeplinks and App Links
        ButtonMerchant.trackIncomingIntent(this, getIntent());
    }


Pass the Button Attribution Token to Your Checkout API

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://api.example.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.example.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);

This concludes handling a user journey from outside applications.