## Add the Button SDK to your Android application

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

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

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

### Kotlin
```kotlin
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")
    }
}
```

### Java
```java
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](https://developer.android.com/studio/build/shrink-code), 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:

```undefined
-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`.

### Kotlin
```kotlin
Button.user().setIdentifier("YOUR_LOGGED_IN_USERS_ID")
```

### Java
```java
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.

### Kotlin
```kotlin
Button.clearAllData()
```

### Java
```java
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.

### Kotlin
```kotlin
// 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)
}
```

### Java
```java
// 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](https://app.usebutton.com/).