Skip to content

Latest commit

 

History

History
279 lines (223 loc) · 9.43 KB

v6_MIGRATION_GUIDE.md

File metadata and controls

279 lines (223 loc) · 9.43 KB
Raw

Braintree Android Drop-In v6 Migration Guide

See the CHANGELOG for a complete list of changes. This migration guide outlines the basics for updating your Braintree Drop-In integration from v5 to v6.

v6 of the Drop-In SDK requires v4 of the Braintree Android SDK.

Table of Contents

  1. Gradle
  2. Builder Pattern
  3. DropInRequest
  4. DropInClient
  5. Authorization
  6. Launch Drop-In
  7. Handle Drop-In Result
  8. Fetch Last Used Payment Method
  9. Browser Switch

Gradle

Add the dependency in your build.gradle:

dependencies {
  implementation 'com.braintreepayments.api:drop-in:6.14.0'
}

The credentials for accessing the Cardinal Mobile SDK have changed.

Update the credentials in your top-level build.gradle to the following:

repositories {
    maven {
        url "https://cardinalcommerceprod.jfrog.io/artifactory/android"
        credentials {
            username 'braintree_team_sdk'
            password 'AKCp8jQcoDy2hxSWhDAUQKXLDPDx6NYRkqrgFLRc3qDrayg6rrCbJpsKKyMwaykVL8FWusJpp'
        }
    }
}

Builder Pattern

The builder pattern has been removed in v6 to allow for consistent object creation across Java and Kotlin. Method chaining has been removed, and setters have been renamed with the set prefix.

For example, a DropInRequest can now be constructed as shown below:

Java:

DropInRequest request = new DropInRequest();
request.setMaskCardNumber(true);

Kotlin:

val request = DropInRequest()
request.maskCardNumber = true

See the Braintree Android v4 Migration Guide for changes to request objects for Google Pay, Venmo, PayPal, and 3DS.

DropInRequest

The getters and setters on DropInRequest have been renamed with a consistent get/set pattern to allow for Kotlin synthesized properties. See the examples below for a full list of optional parameters:

Java:

    DropInRequest dropInRequest = new DropInRequest();
    dropInRequest.setGooglePayRequest(googlePayRequest);
    dropInRequest.setGooglePayDisabled(true);
    dropInRequest.setPayPalRequest(paypalRequest);
    dropInRequest.setPayPalDisabled(true);
    dropInRequest.setVenmoRequest(venmoRequest);
    dropInRequest.setVenmoDisabled(true);
    dropInRequest.setCardDisabled(true);
    dropInRequest.setThreeDSecureRequest(threeDSecureRequest);
    dropInRequest.setMaskCardNumber(true);
    dropInRequest.setMaskSecurityCode(true);
    dropInRequest.setVaultManagerEnabled(true);
    dropInRequest.setAllowVaultCardOverride(true);
    dropInRequest.setVaultCardDefaultValue(true);
    dropInRequest.setCardholderNameStatus(CardForm.FIELD_OPTIONAL);
    dropInRequest.setVaultVenmoDefaultValue(true);

Kotlin:

    val dropInRequest = DropInRequest()
    dropInRequest.googlePayRequest = googlePayRequest
    dropInRequest.isGooglePayDisabled = true
    dropInRequest.payPalRequest = paypalRequest
    dropInRequest.isPayPalDisabled = true
    dropInRequest.venmoRequest = venmoRequest
    dropInRequest.isVenmoDisabled = true
    dropInRequest.isCardDisabled = true
    dropInRequest.threeDSecureRequest = threeDSecureRequest
    dropInRequest.maskCardNumber = true
    dropInRequest.maskSecurityCode = true
    dropInRequest.isVaultManagerEnabled = true
    dropInRequest.allowVaultCardOverride = true
    dropInRequest.vaultCardDefaultValue = true
    dropInRequest.cardholderNameStatus = FIELD_OPTIONAL
    dropInRequest.vaultVenmoDefaultValue = true

The full list of changed parameters is below:

  1. clientTokent -> removed
  2. tokenizationKey -> removed
  3. amount -> removed
  4. intent -> removed
  5. googlePaymentRequest -> googlePayRequest
  6. disableGooglePayment -> googlePayDisabled
  7. paypalRequest -> payPalRequest
  8. disablePayPal -> payPalDisabled
  9. disableVenmo -> venmoDisabled
  10. disableCard -> cardDisabled
  11. vaultManager -> vaultManagerEnabled
  12. vaultCard -> vaultCardDefaultValue
  13. vaultVenmo -> removed
  14. requestThreeDSecureVerification -> removed

The collectDeviceData field has been removed from DropInRequest in favor of always returning device data. The vaultVenmo field has been removed from DropInRequest in favor of setting shouldVault on a VenmoRequest that is set on the DropInRequest The requestThreeDSecureVerification field has been removed from DropInRequest in favor of requesting 3DS if a ThreeDSecureRequest with an amount is set on DropInRequest and the merchant is configured for 3DS.

DropInClient

DropInClient has been added in v6 and replaces the use of an Intent to start Drop-in. See the sections below for code snippets to instantiate a DropInClient with authorization, and launch Drop-in.

Authorization

The clientToken, tokenizationKey, and authorization fields have been removed from DropInRequest. In v6, authorization should be included when instantiating a DropInClient instead.

Option 1: DropInClient with Tokenization Key or Client Token

// Java
DropInClient dropInClient = new DropInClient(<ACTIVITY_OR_FRAGMENT>, "TOKENIZATION_KEY_OR_CLIENT_TOKEN");
// Kotlin
val dropInClient = DropInClient(<ACTIVITY_OR_FRAGMENT>, "TOKENIZATION_KEY_OR_CLIENT_TOKEN")

Option 2: DropInClient with ClientTokenProvider

See example ClientTokenProvider implementation

// Java
DropInClient dropInClient = new DropInClient(<ACTIVITY_OR_FRAGMENT>, callback -> {
    // fetch client token asynchronously...
    callback.onSuccess("CLIENT_TOKEN_FROM_SERVER");
});
// Kotlin
val dropInClient = DropInClient(<ACTIVITY_OR_FRAGMENT>, ClientTokenProvider { callback ->
  // fetch client token asynchronously...
  callback.onSuccess("CLIENT_TOKEN_FROM_SERVER");
})

Launch Drop-In

DropInClient is responsible for launching DropInActivity. To launch Drop-In, instantiate a DropInClient and call DropInClient#launchDropIn:

Java:

DropInRequest dropInRequest = new DropInRequest();
dropInClient.launchDropIn(dropInRequest);

Kotlin:

val dropInRequest = DropInRequest()
dropInClient.launchDropIn(dropInRequest)

Handle Drop-In Result

Implement DropInListener interface in your Fragment or Activity to listen for DropIn results:

// Java
@Override
public void onDropInSuccess(@NonNull DropInResult result) {
  // send payment method nonce server
  String paymentMethodNonce = result.getPaymentMethodNonce().getString();
}

@Override
public void onDropInFailure(@NonNull Exception error) {
  if (error instanceof UserCanceledException) {
    // canceled
  } else {
    // an error occurred, check the returned exception
  }
}
// Kotlin
override fun onDropInSuccess(result: DropInResult) {
  // send payment method nonce server
  val paymentMethodNonce = dropInResult.paymentMethodNonce?.string
}

override fun onDropInFailure(error: Exception) {
  if (error is UserCanceledException) {
    // canceled
  } else {
    // an error occurred, check the returned exception
  }
}

Fetch Last Used Payment Method

Fetching a user's existing payment method has moved from DropInResult#fetchDropInResult to DropInClient#fetchMostRecentPaymentMethod. Note that a payment method will only be returned when using a client token created with a customer_id.

Java:

  DropInClient dropInClient = new DropInClient(this, "CLIENT_TOKEN_WITH_CUSTOMER_ID");
  dropInClient.fetchMostRecentPaymentMethod(this, (dropInResult, error) -> {
    // handle result
  });

Kotlin:

    val dropInClient = DropInClient(this, "CLIENT_TOKEN_WITH_CUSTOMER_ID")
    dropInClient.fetchMostRecentPaymentMethod(this) { dropInResult, error ->
        // handle result
    }

Browser Switch

DropIn handles browser switching internally. Specifying an <intent-filter /> in AndroidManifest.xml is no longer required. Any payment method that requires a browser switch will work automatically.

On the other hand, there are some scenarios that will require you to set a custom URL scheme for browser switch deep linking. For example, if your applicationId contains uppercase letters, you will need to override the default deep link configuration set by the DropIn library.

Internally we use a manifest placeholder to support deep linking into DropInActivity. You can override the deep link intent filter for DropInActivity by placing the following xml snippet in your app's AndroidManifest.xml:

<activity android:name="com.braintreepayments.api.DropInActivity"
  android:exported="true"
  tools:node="merge"
  >
  <intent-filter tools:node="removeAll" />
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="my-custom-url-scheme" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
  </intent-filter>
</activity>

You can then set the custom url scheme on DropInRequest to align with the overridden AndroidManifest.xml value:

dropInRequest.customUrlScheme = "my-custom-url-scheme"

Once set, the DropIn SDK will use this custom url scheme when deep linking instead of the default one.