Developer Experience

[sshropshire]

Developer Experience

We've recently received feedback on migrating from v3 to v4 of our SDK. In v3, the main entry point into the SDK was BraintreeFragment, an Android Fragment subclass. In v4, we extracted the core functionality from BraintreeFragment into BraintreeClient, a plain java object. This improves the modularity of the SDK, increases overall test coverage, and makes it easier to add new features.

On the other hand, there was a slight advantage to subclassing Fragment – the SDK had its own lifecycle. This made integration simple, you could instantiate a BraintreeFragment in either an Activity or a Fragment and you would receive updates from the SDK via listener callbacks.

We recognize how this integration pattern poses fewer architectural restrictions on merchant apps, and we would like to find a way to offer the same v3 experience in v4.

We've internally discussed possible enhancements to our API, and we'd like feedback to see if what we propose meets merchant needs before prioritizing work.

In short, we'd like to:

• Provide an interface for merchants that allows the SDK to fetch client tokens on demand
• Move away from onActivityResult in favor of the new registerForActivityResult Jetpack API
• Fully encapsulate app / browser switching to make integrating with our SDK more simple

Making these changes results in the following API (using PayPal as an example):

// MerchantClientTokenProvider.kt
class MerchantClientTokenProvider: ClientTokenProvider {

    override fun getClientToken(callback: ClientTokenCallback) {
        // asynchronously fetch Braintree client token from your server
        // and call callback.onAuthorizationSuccess(clientToken) when done
    }
}

Then, you may choose to integrate the Braintree SDK into your applicatioin in either an Activity or a Fragment:

// MerchantActivity.kt
class MerchantActivity : AppCompatActivity(), PayPalListener {
    
    lateinit var braintreeClient: BraintreeClient
    lateinit var paypalClient: PayPalClient
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        braintreeClient =
          BraintreeClient(this, MerchantClientTokenProvider())
          
        paypalClient = PayPalClient(this, braintreeClient)
        paypalClient.listener = this
    }
    
    private fun launchPayPal() {
        ...
        paypalClient.tokenizePayPalAccount(this, paypalRequest)
    }
    
    override fun onPayPalTokenizeSuccess(payPalAccountNonce: PayPalAccountNonce) {
        // send nonce to server and create a transaction
    }
    
    override fun onPayPalTokenizeError(error: Exception) {
        // handle error
    }
}

// MerchantFragment.kt
class MerchantFragment: Fragment(), PayPalListener {
    
    lateinit var braintreeClient: BraintreeClient
    lateinit var paypalClient: PayPalClient
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        braintreeClient =
          BraintreeClient(this, MerchantClientTokenProvider())
          
        paypalClient = PayPalClient(this, braintreeClient)
        paypalClient.listener = this
    }
    
    private fun launchPayPal() {
        ...
        paypalClient.tokenizePayPalAccount(this, paypalRequest)
    }
    
    override fun onPayPalTokenizeSuccess(payPalAccountNonce: PayPalAccountNonce) {
        // send nonce to server and create a transaction
    }
    
    override fun onPayPalTokenizeError(error: Exception) {
        // handle error
    }
}

[Yongyong-Zhou]

Which dependency are you using? I can't cite it. @sshropshire

[sshropshire]

@Yongyong-Zhou this constructor will be available in the next release.

[sshropshire]

@Yongyong-Zhou we're holding back on this new constructor for now to make sure we've collected and considered the necessary feedback, but we hope to provide a new, simpler API soon.

[sdoward]

@sshropshire I really appreciate this approach of opening up this discussion and the promptness of it. I certain that it will be beneficial for braintree and consumers alike 🙏

ClientTokenProvider

I think it would be nice if you give a bit more detail in the example code. The devil is in the detail so it would be nice to see how a ClientTokenCallback would be. The comment suggests it will have a method called onAuthorizationSuccess which seems to be odd as the method on the provider doesn't say anything about authorization.

Are we declaring a successful authorization or are we providing a token? It might that internally in the sdk you are using the token for authorization but do you need to expose these concepts to the consumer?

In other words.. as a developer should I be writing authorization code? I guess not.

I guess some of the concerns here are language (java/kotlin) and concurrency right? I presume you have that callback to give the consumer freedom of their concurrency model? But maybe it could be more simple...

public interface TokenProvider {
    String getToken();
}

This way the SDK would be responsible for calling this on a background thread. Consumers would throw if something goes wrong.

I am curious to understand when you need to get that client token? Does the SDK need to be in charge of requesting it? Or can it just accept it as a parameter when the client is tokenising?

paypalClient.tokenizePayPalAccount(token, request, listener,)

Or could it be part of the request object?

paypalClient.tokenizePayPalAccount( request, listener,)

This way would make your SDK completely agnostic to token provision

Integration

As mention in the other thread. I suspect most of your consumers do not want to write payment related code in an Activity or Fragment. I want my code to be unit tested and tightly coupling with Android platform classes make that difficult. I think it would be really beneficial for you to give examples of this new API usage which are complete and not in an Activity or Fragment subclass. e.g.

class PayPalCreator(private val client: PaypalClient) {

    suspend fun createBraintreeNonce(): PayPalAccountNonce {
        val responseDeferred = CompletableDeferred<PayPalAccountNonce>()
        client.tokenizePayPalAccount(Request(), { nonce ->
            responseDeferred.complete(nonce)
        }) { exception ->
            responseDeferred.completeExceptionally(exception)
        }
        return responseDeferred.await()
    }

}

This example would rely on my dependency injection setup to provide the Activity or whatever else when constructing the PaypalClient

I hope that help in someway. And thanks again for the initiative, it looks really promising 💯

[sshropshire]

@sdoward thanks for this. In response:

ClientTokenProvider

We've discussed this internally as well. The intent of the ClientTokenProvider interface is to allow a merchant to asynchronously fetch a client token on behalf of the SDK. The merchant can then invoke the onAuthorizationSuccess callback to notify BraintreeClient that a client token is available.

The naming is a bit off, something like onClientTokenReceived(String) (thoughts on naming?) may be a better solution.

The callback pattern feels like a good choice only because it provides a callback object that returns control back to the internal SDK. It also provides an abstraction layer so the merchant doesn't have to know when or why it was invoked. This can help prevent unnecessary network requests by delaying the request until it is absolutely needed. It also gives us an opportunity to implement a caching mechanism in the future.

It would be interesting to provide a synchronous method to execute in the background for providing a client token. On the other hand popular libraries like okhttp leverage the callback pattern as well, so it is a familiar pattern. We kept this iteration of the SDK in Java mainly to leverage package private to keep as much implementation under the hood as possible. Semantic versioning is another constraint we take seriously to prevent introducing breaking changes into the SDK and package private allows us to make major changes to the internal SDK without affecting the merchant facing API. We are considering library annotations as an alternative to package private, and we'll be exploring Kotlin for the future, in which case a suspend function may be a good solution here.

As an aside, we created the ClientTokenProvider interface partly because of the new registerForActivityResult() API. We want to give merchants the freedom to choose between Fragment and Activity as a point of integration. Doing so will require us to remove our dependency on the deprecated startActivityForResult API. The new activity result api has a restriction that requires the activity launcher to be created no later than onCreate. As a result, any feature client in the SDK that performs an app switch (e.g. VenmoClient) will need to be instantiated in onCreate. Applying this constraint across all features for API consistency, we can now leverage lifecycle observers when browser switching and perform deliverBrowserSwitch internally. By encapsulating this responsibility, we can notify results via listener and we can transfer this burden away from the merchant and onto the SDK.

Integration

This is something that we need to consider. It would be helpful to know if there are a set of libraries that the community would like us to provide explicit support for. While we can't make any guarantees, we may be able to plan and prioritize support based on demand.

[sdoward]

ClientTokenProvider

I think I understand what this is used for thanks for the explanation. However I think this is not a use case for a callback as you have defined it...

Why do you want to burden the consumers/merchants with handling asynchronous tasks? Doing so makes the integration more difficult and makes your api more complex

If we do the opposite, Braintree has the responsibility of handling background and we can use this interface....

public interface TokenProvider {
    String getToken();
}

Internally in your sdk, you can use that provider to call the function on a background thread. Assuming you using threads, you would do something like so...

public class BrainTreeClient {

    private final TokenProvider tokenProvider;

    public BrainTreeClient(TokenProvider tokenProvider) {
        this.tokenProvider = tokenProvider;
    }

    void doSomething() {
        Runnable runnable = new Runnable() {
            public void run() {
                try {
                    String token = tokenProvider.getToken();
                    //handle token
                } catch (Exception exception) {
                    //handle error
                }
            }
        };
        new Thread(runnable).start();
    }

}

But the main thing here is how this would affect the consumers right? Let's compare how a consumer would use my suggestion compared to yours. The following assumes that your sdk will take the TokenProvider in the constructor...

class BraintreeIntegration(val consumerApi: ConsumerApi) {

    fun simpleInterface() {
        BrainTreeClient {
            consumerApi.getToken()
        }
    }

    fun complexCallback() {
        BrainTreeClientComplex(object : ClientCallBackProvider {
            override fun getClientToken(callback: ClientTokenCallback) {
                GlobalScope.launch { 
                    try {
                        val token = consumerApi.getToken()
                        callback.onAuthorizationSuccess(token)   
                    } catch (exception: Exception) {
                        // You didn't mention how errors would be handled in your proposal
                    }
                }
            }

        })
    }

}

It would be just as convoluted if the consumer used any other concurrency model.

So I want to be pretty clear (but hopefully not rude). This is a really bad idea. I feel like this is a misunderstanding of what a callback should be used for.

I think this misunderstanding is represented in the link to okhttp that you shared. OkHttp uses them to great affect BUT you have a different use case.

Here is the difference...

OKHttp is providing data to the consumers asynchronously
Braintree is asking consumers to provide data asynchronously

But as I mentioned earlier you don't have to make the consumers do that. So your usecase becomes...

Braintree asks the consumer to provide a token

There is nothing wrong with callback, they work great. But just not like this.

Access Modifiers

Yes, it make complete sense to use private modifiers to hide internal implementations. This is a basic language feature in the JVM world which is used by nearly every developer. It's is not really a "consideration" for a library but more of a fundamental when using java/kotlin. Which worries me how you mention visibility modifiers in the same context as the suspend key word. Suspend key word is used as part of the coroutines concurrency model.

I am a little confused as to how that has any impact on semantic versioning. Which is a great idea for any library maintainer, it's just not related to the other concepts.

RegisterForActivityResult

That all sounds really promising!

But my main concern is this sentence... We want to give merchants the freedom to choose between Fragment and Activity

As I mentioned in the previous comment consumers don't want to be writing code in a fragment nor activity. Which leads me to the last point...

Integration

I think you may have misunderstood why I have this example. The main reason was to demonstrate that I don't want this code to be in an Activity or Fragment. I just happened to write the example using coroutines because I wanted to show how I would tie it in with no-blocking code... But I wanted to show how your async/java code could be agnostic to the consumers setup.

To be clear
Don't want: Activity/Fragment coupling
Do want: Concurrency agnostic apis

I worry you got the opposite message there. To add to my previous example I will show it written with RxJava with the same assumed API of your sdk..

class PayPalCreator(private val client: PaypalClient) {

    fun createBraintreeNonce(): Single<PayPalAccountNonce> {
        return Single.fromCallable {
            client.tokenizePayPalAccount(Request(), { nonce ->
                nonce
            }) { exception ->
                throw exception
            }
        }
    }

}

Also with a callback with the same assumed api...

class PayPalCreator(private val client: PaypalClient) {

    fun createBraintreeNonce(nonceListener: (PayPalAccountNonce) -> Unit) {
        client.tokenizePayPalAccount(Request(), { nonce ->
            nonceListener(nonce)
        }) { exception ->
            throw exception
        }
    }

}

For clarity, also with coroutines...

class PayPalCreator(private val client: PaypalClient) {

    suspend fun createBraintreeNonce(): PayPalAccountNonce {
        val responseDeferred = CompletableDeferred<PayPalAccountNonce>()
        client.tokenizePayPalAccount(Request(), { nonce ->
            responseDeferred.complete(nonce)
        }) { exception ->
            responseDeferred.completeExceptionally(exception)
        }
        return responseDeferred.await()
    }

}

So that is to say. If you provide a simple, agnostic API which is not bound to system classes: then you don't need to worry about providing support for other libraries because the integration becomes super simple for the consumers.

[sdoward]

@sshropshire is there any update on this discussion? I am really interested to see how it develops

[sdoward]

Coincidentally I have been updating a Stripe dependency today. I thought it would be interesting to share how that API works. It is super easy to use. https://stripe.com/docs/google-pay

Please note, although the example is a subclass of an Activity it doesn't require for consumers to follow that pattern

[sshropshire]

@sdoward yes this is still up for discussion. We've been focusing on feature work at the moment, but we will look to improve the developer experience fully in our next major v5 version. We don't have a timeline, but it is something we actively discuss.

I like the idea of decoupling from Android as much as possible. Some of the advancements the Google team has made with Hilt offer us a lot of flexibility with future APIs.

We did release a new integration pattern with ClientTokenProvider in v4.9.0 of our SDK to help out merchants who need more flexibility now, but we will continue to consider your suggestions for v5 in a collaborative way.

We really appreciate the input in helping improve our SDK as it evolves. 🙏