> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/id-fraud-shield-sdk/integration-guide/ios/integration-steps.md).

# Integration Steps

This section explains the core integration flow of the VIDA Shield SDK within an iOS application. Each step ensures the correct initialization, submit, and cleanup of the SDK lifecycle.

## Import VIDA Shield

The first step is to import the VidaShield class into your Application start.\
This class serves as the entry point for all operations — initialization, starting and submitting the data for verification, and releasing resources.

```kotlin
import vidaShield
```

## Initialize Shield SDK

To start using the Shield SDK, the first step is to **initialize the SDK** with the required configuration values such as **API Key, License Key, Client ID, and Client Transaction ID**. Initialization should be done **once at app launch** (e.g., `AppDelegate` / `SceneDelegate`) **before calling any other Shield SDK APIs**.

<table data-full-width="true"><thead><tr><th width="189.62109375">Option</th><th width="87.11328125">Type</th><th>Description</th></tr></thead><tbody><tr><td>clientTransactionID</td><td>String</td><td><strong>Mandatory</strong> : This is client’s transactionID for the specific flow, this will also used by customer to fetch the fraud details from backend</td></tr><tr><td>userId</td><td>String</td><td><strong>Mandatory</strong>: UserID or hash of the UserID. This will help to configure rules around users.</td></tr><tr><td>Flow</td><td>String</td><td><strong>Optional</strong>: This is the flow type where SDK is used for example : login, profile page, transaction page etc.</td></tr><tr><td>apiKey</td><td>String</td><td><strong>Mandatory</strong>: This is provided by VIDA</td></tr><tr><td>licenseKey</td><td>String</td><td><strong>Mandatory</strong>: This is provided by VIDA</td></tr><tr><td>clientId</td><td>String</td><td><strong>Mandatory</strong>: This is provided by VIDA</td></tr></tbody></table>

<details>

<summary>Initialize SDK</summary>

```kotlin
VidaShield.initialize(with: VidaShieldConfig
 (
     apiKey: Constants.apiKey,      //  Mandatory Shared by VIDA                                        
     licenseKey:Constants.licenseKey, // Mandatory Shared by VIDA   
     clientId: Constants.clientId, //  Mandatory Shared by VIDA   
     clientTransactionId: transactionId, // Mandatory
     userHashId: userHash,
     flow: flow
  )
)
//Note: If isInitialized() returns true, it indicates that the //SDK is already initialized. If the application needs to //reinitialize the SDK due to a configuration update, use the //updateConfiguration() API. To force a fresh initialization, //call release() first and then initialize the SDK again.
```

</details>

## isSDKInitialized() method&#x20;

This method returns the status of SDK and it returns boolean status true/false.

## Call SubmitData API

The `submitData()` is an asynchronous SDK call method that begins the  submission  process of collected data to the Vida server for analysis. Customers can call VIDA’s  backend API to fetch the transaction details using clientTransactionID.

Use `VidaShield.submitData()`  to trigger data submission. The SDK returns a `VidaShieldResponse` in the completion block. Check status to confirm whether submission succeeded.

`VidaShieldResponse` contains:

* **status** → indicates success or failure
* **successDetails** → additional data or error information returned by the SDK
* **errorDetails** → error information like error code and error message. Application should log this information.&#x20;

```kotlin
VidaShield.submitData {[weak self] response in
            guard let self else { return }
            
            if response.status {
                // On success
            } else {
                // On Failure
                Log(response.errorDetails?.errorCode ?? 1)
            }
        }
```

```kotlin
@objc public class VidaShieldResponse: NSObject, Codable {
    public let status: Bool
    public let successDetails: VidaShieldSuccessDetails?
    public let errorDetails: VidaShieldErrorDetails?
}

@objc public class VidaShieldErrorDetails: NSObject, Codable {
    public let errorCode: Int?
    public let errorMessage: String?
}
@objc public class VidaShieldSuccessDetails: NSObject, Codable {
    public let clientTransactionId: String
}
```

## updateConfiguration API

`updateConfiguration()` is an asynchronous SDK API that allows the application to update configuration parameters **after** the SDK has been initialized.

This is useful when some values—such as **flowType, transactionId / clientTransactionId, or userHashId**—are not available during the initial setup and need to be provided or updated later in the user journey.Only the provided non-empty values are updated; `nil` or empty values will not override existing configuration. All value is optional.

This API also includes an optional **escaping completion callback** that returns a `VidaShieldResponse`. You can verify whether the update succeeded by checking `response.status` (<mark style="color:$success;">**`true`**</mark> = success). If the update fails, refer to `response.errorDetails` for the failure reason.

```kotlin
 VidaShield.updateConfiguration(with:
            VidaShieldUpdateConfig(clientTransactionId: nil, userHashId: userHash, flow: "dashboard")
        ) {[weak self] response in
            guard let self else { return }
            
            if response.status {
                // On successs
            } else {
                // On failure
                Log.error(response.errorDetails?.errorMessage ?? "")
            }
        }
```

## Release Resources

```kotlin
VidaShield.releaseSDK()
```

`releaseSDK()` is used to **fully reset the SDK**. It clears all stored configuration and cached data, releases internal resources, and frees up memory used by the SDK.

{% hint style="danger" %}
**Warning**: Call this only when you **do not plan to continue using the SDK with the current configuration**, because it will remove existing config and state.
{% endhint %}

Use `releaseSDK()` if you want to **switch to a new configuration** and then initialize the SDK again with fresh/updated config values.

Do not call `releaseSDK()` if you want to keep using the SDK with the same configuration (use `updateConfiguration()` instead for updating only specific values).

## VidaShieldConfig Implementation

The VIDAShieldConfig class defines the configuration parameters for the Shield sdk.

```kotlin
var config = VidaShieldConfig(apiKey: Constants.apiKey,// Shared by VIDA  
                              licenseKey: Constants.licenseKey,//Shared by Vida
                              clientId: Constants.clientId, //Shared by VIDA  
                              clientTransactionId: transactionId, //Mandatory 
                              userHashId: userHash, // Optional
                              flow: flow)// Optional 
```

### Parameters

<table data-full-width="true"><thead><tr><th width="189.62109375">Option</th><th width="87.11328125">Type</th><th>Description</th></tr></thead><tbody><tr><td>apiKey</td><td>String</td><td><strong>Mandatory</strong>: This is provided by VIDA</td></tr><tr><td>licenseKey</td><td>String</td><td><strong>Mandatory</strong>: This is provided by VIDA</td></tr><tr><td>clientId</td><td>String</td><td><strong>Mandatory</strong>: This is provided by VIDA</td></tr><tr><td>clientTransactionID</td><td>String</td><td>UUID for current app session</td></tr><tr><td>userHashId</td><td>String</td><td>Hash string of logged user id</td></tr><tr><td>Flow</td><td>String</td><td>Flow type: <strong>login</strong>, or <strong>dashboard</strong>, <strong>payment_flow</strong></td></tr></tbody></table>