Quick Start Guide for Ansa (Android)¶

Overview¶

Ansa simplifies the integration of powerful features into your mobile apps.The Ansa Mobile SDKs focus on both ease of integration and flexibility for customization. Our SDKs make it incredibly simple to interface with the Ansa APIs and provide developers out of the box UI. We provide two SDKs that give developers as little or as much control as they want of the user experience. This guide will help you get started with integrating the Ansa SDK into your Android application. Follow these steps to quickly set up and begin using Ansa’s mobile SDK.

Step 1: Setup your environment¶

The Ansa Android SDK is fully documented, and compatible with apps supporting Android 8.0 (API 26) and above.

To install the SDK, follow these steps:

Add the following dependencies in your app/module build.gradle file:

dependencies {
    // Replace with the latest version
    implementation 'com.getansa:sdk-core:<version>'
    implementation 'com.getansa:sdk-ui:<version>'
}

Make sure your repositories block includes mavenCentral() in your root build.gradle.

Step 2: Setup Customer¶

First, you'll need you a few secret keys and identifiers which we will create in the Ansa portal, as well as your Merchant ID and Merchant Secret Key.

• Merchant Publishable Key
• Client Secret Key

We can do so by creating a customer in the portal.

Create a Customer¶

To get started, click "Add Customer" and fill in the customer details.

Once the customer is created you'll see the new customer in the list. Click it to access the overview.

Customer Overview¶

The customer overview gives you all the information for the customer, but we are after 2 things here - the Customer ID and the Client Secret Key.

The Customer ID is available along the left hand side, under the name, email and phone number (omitted from the images).

To create a Client Secret Key tap "Client Secrets" and then "Generate Key".

NOTE: Client Secret Keys generated here are for testing only and expire after 7 days. These should not be used in production. See here for more details on payment sessions.

Merchant Publishable Key¶

To obtain your merchant publishable key, click the Settings icon in the top right and tap "API Keys" under Developer.

With our identifiers and secrets in hand, we are ready to integrate.

Step 3: Initialize AnsaClient¶

Everything data related for your customers and merchant information is available through the AnsaClient. To initialize the client can be as simple as 4 lines of code.

val ansaClient: AnsaClient = AnsaClient.init(
    publishableKey = "merchant publishable key from portal API keys",
    clientSecretProvider = ClientSecretProviderImpl()
)

At the bare minimum an AnsaClient requires the merchant publishable key and a ClientSecretProvider. The ClientSecretProvider interface allows our AnsaClient to request a secret key from your Backend for a given Ansa Customer ID. However, for this demo we will utilize the testing secret key we generated.

public class ClientSecretProviderImpl : ClientSecretProvider {
  override suspend fun provideClientSecret(ansaCustomerId: String): String? {
    // Hit client their backend, which calls initialize session w/ merchant secret
    // returns PaymentSession json payload
    // client needs to parse it and pass it to us

    return getClientSecretFromBackend()
  }

  private suspend fun getClientSecretFromBackend(): String? {
    return "secret-key-from-portal"
  }
}

Step 4: Receive API results¶

Once we have an initialize AnsaClient, we can query any data we need through the accessible managers - CustomerManager and MerchantManager - which are named respective to what they are scoped to and provide.

viewModelScope.launch {
    val customerResult: ApiResult<Customer> = ansaClient.customer.get(customerId)
    val paymentMethodsResult: ApiResult<List<PaymentMethod>> = ansaClient.customer.getPaymentMethods(customerId)
    val merchantResult: ApiResult<Merchant> = ansaClient.merchant.get(merchantId)
}

All manager methods return an ApiResult, which is similar to Kotlin's Result, which means you get familiar extensions off of the result.

viewModelScope.launch {
    val customer: Customer? = ansaClient.customer.get(customerId).getOrNull()
    ansaClient.customer.get(customerId)
        .map { customer ->
            // do something with customer
        }
        .onSuccess { customer ->
            // use result
        }
        .onError { error: Throwable ->
            error.printStackStrace()
        }
}

Step 5: Display your customers wallet¶

We provide a complete wallet experience via our WalletScreen that is drop-in ready for your app.

It's as simple as

 class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            AnsaTheme {
                AnsaWalletScreen(
                    ansaClient = ansaClient,
                    customerId = { customerId },
                    merchantId = { merchantId },
                )
            }
        }
    }
}

Advanced¶

Logging¶

AnsaClient supports allowing you to hook up any logging internally in AnsaClient to your preferred logging framework (Timber, Kermit, LogCat, etc.) via a logging plugin during init().

private val ansaClient: AnsaClient = 
    AnsaClient.init(
        logging = Logging(
            level = LogLevel.ERROR, 
            log = { message: String -> Timber.e(message) }
        ), 
        publishableKey = "merchant publishable key from portal API keys",
        clientSecretProvider = ClientSecretProviderImpl()
    )

Self Managed UI¶

We also provide a way to self manage the UI which provides and allows you to:

• Ready-to-Use Views: Use, customize, and populate our pre-built UI components.
• Handle User Events: You retain full control over user interactions, allowing you to trigger custom logic or communicate with your backend systems as needed.
• Ideal for Customization: This option is perfect if you want out-of-the-box UI elements but need to handle specific user events and maintain fine-grained control over the user experience.

To learn more check out our more in-depth documentation here