# iOS 

> Learn how to integrate the independent card binding SDK into an iOS client.

In this topic, you'll learn how to integrate the embedded card vaulting SDK into an iOS client. This can help you embed the card vaulting block into your checkout page in a mobile application.

---

## Prerequisites

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

- Install the latest version of Xcode.
- Use iOS 11.0 or later.
- Configure a physical machine or emulator to run your application.

---

## Key integration steps

Integrate the embedded 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 iOS](https://docs.antom.com/ac/sdks/ios.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:
   - **locale**: 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
   - **environment**: Required. Used to specify whether to use the sandbox environment. Valid values:
     - `AMSEnvironment.sandbox`: Sandbox environment
     - `AMSEnvironment.production`: Production Environment
   - **notRedirectAfterComplete**: Optional, Boolean type. 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 **AMSVaultingDelegate** protocol 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 **AMSVaultingDelegate** to the *configuration* instance for executing event callbacks.

4. Instantiate `AMSVaulting`.

**Example - Create an SDK instance:**

```swift
// Create configuration
let configuration = AMSVaultingConfiguration()
configuration.locale = "en_US"
// Set sandbox environment
configuration.environment = .sandbox

// Set delegate
configuration.delegate = self

// Create vaulting
let vaulting = AMSVaulting(configuration: configuration)

// Implement delegate method
extension ViewController: AMSVaultingDelegate {
    func onEventCallback(eventCode: String, eventResult: AMSEventResult?) {
        print("Event code: \(eventCode)")
        if let result = eventResult {
            print("Event result: \(result)")
        }
    }
}
```

### 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 `create` in the instance object to create the card vaulting element collection component

**Merchant client**

1. Call the `create(in: sessionData:)` method and pass in the following parameters:
   - *view*: Required. UIView type object, used to contain the vaulting component view.
   - *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 `destroy()` 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 create():**

```swift
// view is the container for the vaulting component
vaulting.create(in: view, sessionData: sessionData)

// Unmount component
vaulting.destroy()
```

---

## 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.

```swift
// Create configuration
let configuration = AMSVaultingConfiguration()
configuration.locale = "en_US"
// Set sandbox environment
configuration.environment = .sandbox

// Set delegate
configuration.delegate = self

// Create vaulting
let vaulting = AMSVaulting(configuration: configuration)

// You must initiate a createVaultingSession request to the Antom server before calling the following
// view is the container for the vaulting component
vaulting.create(in: view, sessionData: sessionData)

// Implement delegate method
extension ViewController: AMSVaultingDelegate {
    func onEventCallback(eventCode: String, eventResult: AMSEventResult?) {
        print("Event code: \(eventCode)")
        if let result = eventResult {
            print("Event result: \(result)")
        }
        
        switch eventCode {
        case "SDK_ASSET_BINDING_SUCCESSFUL":
            // Card vaulting is successful. The SDK needs to be revoked. It is recommended to redirect to the card vaulting result page.
            break
        case "SDK_ASSET_BINDING_FAIL":
            // Card vaulting failed. We suggest that you follow the vaultingResultCode error code prompt and guide the buyer to retry card vaulting.
            break
        case "SDK_ASSET_BINDING_ERROR":
            // Card vaulting is abnormal. We suggest that you wait for the card vaulting result notification or redirect the buyer to retry card vaulting.
            break
        default:
            // Other custom event or errors
            break
        }
    }
}
```

---

## 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. |

---