# Android

> Learn how to integrate the pop-up card vaulting SDK with an Android client.

In this topic, you'll learn how to integrate the pop-up card vaulting SDK with an Android client. This will allow you to render the card vaulting page in a mobile application.

---

## Prerequisites

Before the integration, ensure that you have completed the following tasks:

- Install the latest version of Android Studio.
- Use target API level 19 or later.
- Use Gradle 4.1 or later.
- Configure a physical machine or emulator to run your application.

---

## Key integration steps

Integrate the independent card vaulting SDK by following these steps:

### Step 1: Integrate the SDK package

**Merchant client**

To integrate the SDK package, please refer to [Integrate the SDK Package for Android](https://docs.antom.com/ac/sdks/android.md).

### Step 2: Create an SDK instance using `AMSVaulting`

**Merchant client**

The process of creating an SDK instance includes the following steps:

1. Create a **configuration** object: Required. Object type, which includes the following parameters:
   - **setLocale**: Optional. String type. It is used by the merchant client to identify the browser language and pass in the language information. The SDK uses the information to render the cashier page in the corresponding language. Valid values are listed as follows. If other values are passed, English is used by default:
     - `"en", "US"`: English
     - `"pt", "BR"`: Portuguese
     - `"ko", "KR"`: Korean
     - `"es", "ES"`: Spanish
     - `"fr", "FR"`: French
     - `"nl", "NL"`: Dutch
     - `"it", "IT"`: Italian
     - `"de", "DE"`: German
     - `"zh", "CN"`: Simplified Chinese
     - `"zh", "HK"`: Traditional Chinese
   - **setOption**: Optional. Used to specify whether to use the sandbox environment. Valid values are:
     - `"sandbox", "true"`: Sandbox environment.
     - `"sandbox", "false"`: Production Environment.
     - `"notRedirectAfterComplete", "true"`: The default value is `false`, indicates that redirection to your page takes place after the card vaulting is complete. The same applies when the value is empty. When the value is `true`, redirection will not take place after the card vaulting is complete. You need to use the customer event code to control the card vaulting and complete the subsequent process. Please note that the card vaulting result event code returned by the client is only used as a reference for the redirection of the client page. For transaction status updates, please refer to the results returned by [notifyVaulting](https://docs.antom.com/ac/apo/notify_vaulting.md) or [inquireVaulting](https://docs.antom.com/ac/apo/inquire_vaulting.md).

2. Create an instance of the **OnCheckoutListener** API to handle corresponding events that occur in the subsequent process. It contains the following function:
   - `OnEventCallback`: Required. The card vaulting event callback function that returns *eventCode* and *eventResult*.

3. Set the instance of the **onCheckoutListener** API to the *configuration* instance for executing event callbacks.

4. Instantiate `AMSVaulting`.

**Example - Create an SDK instance:**

```java
AMSVaultingConfiguration configuration = new AMSVaultingConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Set sandbox environment instead of online production environment.
configuration.setOption("sandbox", "true");
// Configure checkout callback listener 
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());
    }
});
// Instantiate AMSVaulting 
AMSVaulting checkout = new AMSVaulting.Builder(activity, configuration).build();
```

### Step 3: Initiate a createVaultingSession request

**Merchant server**

The merchant client monitors the click events of the **Add Card** button itself. When the buyer selects a payment method and clicks the card vaulting button, the merchant server sends the [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md) request to the Antom server. Once the response to the [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md) request is received, the *vaultingSessionData* value in the response is used in step 4.

If you need to automatically redirect buyers to your page after card vaulting is complete, pass in the *redirectUrl* field in the [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md) API. If you want to control the subsequent process of card vaulting through client-side event codes, you do not need to pass in the *redirectUrl* field. You can monitor the card vaulting result event code through `onEventCallback`.

> **Note**: The vaulting result event code returned by the client is only used as a reference for redirection operations on the client page. Please refer to the [notifyVaulting](https://docs.antom.com/ac/apo/notify_vaulting.md) API on the server for updates on the vaulting status.

**Example - createVaultingSession request:**

```json
{
  "paymentMethodType": "CARD",
  "vaultingRequestId":"vaultingRequestId_001",
  "vaultingNotificationUrl": "https://www.example.com.sg",
  "redirectUrl": "https://www.example.com"
}
```

### Step 4: Use `createComponent` in the instance object to create the card vaulting element collection component

**Merchant client**

1. Call the `createComponent()` method and pass in the following parameters:
   - *activity*: Required. Activity type object, used to contain contextual parameter information for the current page.
   - *sessionData*: Required. String type. Pass in the complete data of the *vaultingSessionData* field obtained from the response of the [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md) request into the *sessionData* parameter.

2. Free resources of the SDK component by calling the `onDestroy()` method in the instance object. You need to unmount the component in the following cases:
   - When the buyer exits the card vaulting page, free the component resources created in [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md).
   - When the buyer initiates card vaulting multiple times, free the component resources previously created in [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md).

**Example - Call createComponent():**

```java
checkout.createComponent(activity,sessionData);
// Unmount component
checkout.onDestroy();
```

---

## Sample code of key integration steps

The following sample code demonstrates the key steps in the integration process. The code does not include examples of calling the [createVaultingSession](https://docs.antom.com/ac/apo/vaulting_session.md) API. You need to handle the server API calls on your own.

```java
AMSVaultingConfiguration configuration = new AMSVaultingConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Set sandbox environment instead of online production environment.
configuration.setOption("sandbox", "true");
// Configure checkout callback listener
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        Log.e(TAG, "onEventCallback eventCode=" + eventCode + " eventResult=" + eventResult.toString());
        if (!TextUtils.isEmpty(eventCode)) {
            if ("SDK_ASSET_BINDING_SUCCESSFUL".equals(eventCode)) {
                // Card vaulting is successful. The SDK needs to be revoked. It is recommended to redirect to the card vaulting result page.
            } else if ("SDK_ASSET_BINDING_FAIL".equals(eventCode)) {
                // Card vaulting failed. We suggest that you follow the vaultingResultCode error code prompt and guide the buyer to retry card vaulting. 
            } else if ("SDK_ASSET_BINDING_ERROR".equals(eventCode)) {
                // Card vaulting is abnormal. We suggest that you wait for the card vaulting result notification or redirect the buyer to retry card vaulting.
            } else {
                // Other custom event or errors
            }
        }
    }
});
// Instantiate AMSVaulting
AMSVaulting checkout = new AMSVaulting.Builder(activity, configuration).build();
// You must initiate a createPaymentSession request to the Antom server before calling the following

checkout.createComponent(activity,sessionData);
// When the page exits or when required to re-call createComponent, you must unmount the component first 
checkout.onDestroy();
```

---

## Event codes

The SDK may return the following event codes during the card vaulting process:

| Event Code | Description |
|------------|-------------|
| `SDK_ASSET_BINDING_SUCCESSFUL` | Card vaulting is successful. |
| `SDK_ASSET_BINDING_FAIL` | Card vaulting failed. |
| `SDK_ASSET_BINDING_ERROR` | Card vaulting encountered an error. |

---