Overview

Ansa’s React Native SDK makes it incredibly simple to interface with Ansa’s APIs and provide developers an out of the box UI.

There are two components to the React Native SDK:

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 React Native application.

Step 1: Setup your environment

The React Native SDK is compatible with apps supporting iOS 16 or above and Android 8.0 (API 26) and above.

Install the SDK using npm or Yarn:

npm install ansa-react-native

or

yarn add ansa-react-native

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

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 Ansa

Initialize the Ansa SDK in your React Native app by wrapping your app with the AnsaProvider component:.

import React from 'react';
import { AnsaProvider } from 'ansa-react-native-sdk';

export default function App() {
  return (
    <AnsaProvider
      apiKey="your-merchant-publishable-key"
      clientSecretProvider={clientSecretProvider}
    >
      {/* Your app components */}
    </AnsaProvider>
  );
}

Implement the clientSecretProvider function to supply the Client Secret Key. The clientSecretProvider allows us 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.

const clientSecretProvider = async (ansaCustomerId) => {
  // Fetch the client secret from your backend
  // Replace with your logic
  return 'your-client-secret-key';
};

Step 4: Receive API results

Once we have initialized the Ansa SDK, we can query any data we need. For example, you can fetch customer or merchant information as demonstrated below:

import {
  getCustomer,
  getMerchant,
} from 'ansa-react-native';

// Fetch a customer with specified customerId
const fetchAnsaCustomer = async () => {
  try {
    const customer = await getCustomer(customerId);
    console.log(`Customer data: ${JSON.stringify(customer)}`);
  } catch (error) {
    console.error(`Fetch Customer failed: ${error}`);
  }
};

// Fetch merchant information with specified merchantId
const fetchAnsaMerchant = async () => {
  try {
    const merchant = await getMerchant(merchantId);
    console.log(`Merchant data: ${JSON.stringify(merchant)}`);
  } catch (error) {
    console.error(`Fetch Merchant failed: ${error}`);
  }
};

Step 5: Displaying Ansa UI

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

You can instantiate the view using the following:

import { ManagedAnsaBalanceScreen } from 'ansa-react-native';

function YourComponent() {
  return (
    <ManagedAnsaBalanceScreen
      customerId="your-customer-id"
      merchantId="your-merchant-id"
    />
  );
}

Advanced Usage

Logging

Ansa supports allowing you to hook up any logging internally to your preferred logging framework via a logging plugin during initialization. You can configure both the log level and a custom logging function:.

import { AnsaProvider, LogLevel } from 'ansa-react-native';

export default function App() {
  const handleLog = (message) => {
    // Hook into your preferred logging framework
    console.log('[Ansa React Native SDK]', message);
  };

  return (
    <AnsaProvider
      apiKey="your-merchant-publishable-key"
      clientSecretProvider={clientSecretProvider}
      logLevel={LogLevel.Verbose}
      logger={handleLog}
    >
      {/* Your app components */}
    </AnsaProvider>
  );
}

Expo

The Ansa React Native SDK is compatible with Expo. To use the SDK with Expo, you need to install the Ansa module and then re-build your native code project using Expo. For Android, you may need to manually set the min SDK version in app.json.

"plugins": [
  [
    "expo-build-properties",
    {
      "android": {
        "minSdkVersion": 26,
        "compileSdkVersion": 34,
        "targetSdkVersion": 34,
      }
    }
  ]
],