Overview

Ansa’s mobile SDKs make it incredibly simple to interface with Ansa’s APIs and provide developers a customizable, out of the box UI.

We provide two SDKs:

1. Ansa Core – a headless core SDK that lets you fully manage your own UI
2. Ansa UI – immediately usable UI SDK with pre-built components, which uses Ansa Core under the hood.

This guide will get you started with integrating the Ansa SDK into your iOS application.

Step 1: Setup your environment

The Ansa iOS SDK is fully documented, and compatible with apps supporting iOS 16 or above.

To install the SDK, follow these steps:

1. In Xcode, select File > Add Packages... and enter https://github.com/GetAnsa/ansa-ui-ios as the repository URL.
2. Select the latest version number from our releases page.
3. Add the AnsaCore product to the target of your app.

Note: For details on the latest SDK release and past versions, see the Releases page on GitHub.

To receive notifications when a new release is published, watch releases for the repository.

Step 2: Setup a Customer

First, you'll need certain API keys and identifiers, which are accessible/can be created in the Ansa portal. In total, you'll need:

• Merchant ID – the unique identifier for your merchant account
• Merchant Publishable Key – a publishable API key that is safe to include in client-side code. Used to initialize the client-side SDKs and is authorized to invoke select API endpoints
• Client Secret Key – a short lived key scoped to a specific Customer meant to be used by client-side code

Creating a Customer

To quickly get started, let's create a Customer using the Ansa Portal. Click Add customer and fill in customer details.

📘

Production note

In production, you'll want to use the API (such as from your backend) to create a customer and link it to your internal definition, as opposed to using the portal to create customers.

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

From here you'll need to retrieve the Customer ID and create a 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. They are not meant to be hardcoded for production use.

In production, you'll want to use payment sessions to regenerate client secret keys via the API. 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 click "API Keys" under Developer.

You now have everything you need to test the SDK!

Step 3: Initialize AnsaClient

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

AnsaSdk.initialize(
  publishableKey: "merchant publishable key from portal API keys",
  clientSecretProvider: ClientSecretProviderImpl()
)

At the bare minimum, an AnsaClient requires the merchant publishable key and a ClientSecretProvider instance. 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 client secret key we generated earlier.

class ClientSecretProviderImpl: ClientSecretProvider {
  func provideClientSecret(ansaCustomerId: String) async -> 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 "secret-key-from-portal"
  }
}

Step 4: Receive API results

Once we have an initialized AnsaClient, we can query any data we need through the accessible managers - CustomerManager and MerchantManager - which are named accordingly.

let ansa = AnsaSdk.shared
let customerResult = await ansa.customer.get(customerId: customerId)
let paymentMethodsResult = await ansa.customer.getPaymentMethods(customerId: customerId)
let merchantResult = await ansa.merchant.get(merchantId: merchantId)

All manager methods return a Swift.Result, which means you get familiar extensions off of the result.

let result = await ansa.customer.get(customerId: customerId)
return switch result {
    case .success(let successObject):
      "\(successObject)"
    case .failure(let failure):
      failure.humanReadableMessage
    }

Step 5: Trying the UI

The Ansa UI SDK provides a complete wallet UI component via the AnsaManagedBalanceScreen that can be dropped into your app.

You can instantiate the view using the following:

ManagedAnsaBalanceScreen(
      ansaClient: ansaClient,
      customerId: "ansa_customer_id",
      merchantId: "your_merchant_id"
    )
    // Customize the navigation bar
    .ansaNavigationBar(
      title: "Wallet",
      leadingSlot: {
        Image(systemName: "arrow.backward")
          .frame(width: 24, height: 24)
          .onTapGesture {
              // Handle closing screen
          }
      }
    )

Advanced Usage

Logging

Ansa supports allowing you to hook up any logging internally in AnsaClient to your preferred logging framework (swift-log, SwiftyBeaver, etc.) via a logging plugin during initialize().

AnsaSdk.initialize(
  logging: Logging(level: LogLevel.error, log: { message in logger.error(message)}),
  publishableKey: "merchant publishable key from portal API keys",
  clientSecretProvider: ClientSecretProviderImpl()
)

For more details, you can check out the Swift API reference here. If you have any other specific questions or need further guidance, please reach out to your implementation manager!