# Integrate the Virtual Cards Simulator SDK

## Prerequisites

1. [Complete the Getting Started Guide](https://docs.sudoplatform.com/guides/getting-started)

## Get Started

* [Integrate the JS SDK](#integrate-the-js-sdk)
* [Integrate the iOS SDK](#integrate-the-ios-sdk)
* [Integrate the Android SDK](#integrate-the-android-sdk)

## Integrate the JS SDK

To use the **Virtual Cards Simulator SDK** in a Web or Node.js project, you must add `@sudoplatform/sudo-virtual-cards` as a dependency to your project.

```
yarn add '@sudoplatform/sudo-virtual-cards-simulator'
# or
npm install --save '@sudoplatform/sudo-virtual-cards-simulator'
```

To instantiate and initialize a client in your application, add the following:

{% tabs %}
{% tab title="TypeScript" %}

```javascript
const SimApiConfig = t.type({
  apiUrl: t.string,
  apiKey: t.string,
  region: t.string,
})
type SimApiConfig = t.TypeOf<typeof SimApiConfig>

const setupApiClient = (): AWSAppSyncClient<NormalizedCacheObject> => {
  const config =
    DefaultConfigurationManager.getInstance().bindConfigSet<SimApiConfig>(
      SimApiConfig,
      'vcSimulator',
    )
  return new AWSAppSyncClient({
    disableOffline: true,
    url: config.apiUrl,
    region: config.region,
    auth: {
      type: AUTH_TYPE.API_KEY,
      apiKey: config.apiKey,
    },
  })
}

const client = setupApiClient()
const virtualCardsSimulatorClient =
  new DefaultSudoVirtualCardsSimulatorClient({ appSyncClient: client })
```

{% endtab %}
{% endtabs %}

## Integrate the iOS SDK

The [iOS SDK](https://github.com/sudoplatform/sudo-virtual-cards-ios) is open source and compatible with iOS 11 and above.

To use the Virtual Cards Simulator SDK in an iOS app, you need to install the SudoVirtualCardsSimulator package via Swift Package Manager

Open your project settings in XCode, and go to the `Package Dependencies` tab. Click on the `+` sign to add a dependency.&#x20;

Enter the repository URL [`https://github.com/sudoplatform/sudo-virtual-cards-simulator-ios`](https://github.com/sudoplatform/sudo-virtual-cards-simulator-ios) in the top right search box and select the `sudo-virtual-cards-simulator-ios` repository.&#x20;

Select the required version and `Add Package`.&#x20;

Sudo Platform SDKs conform to semantic versioning so in most cases you will leave the Dependency Rule as `Up to Next Major Version` to receive regular updates without introducing any breaking changes.

This will resolve the local package dependency and install the latest version of the Virtual Cards Simulator SDK.

**SDK Configuration**

{% hint style="info" %}
Simulator configuration differs from the configuration of the other Sudo Platform SDKs.\
**Please take note of this section.**
{% endhint %}

The Simulator configuration differs from the configuration you will have seen in the other Sudo Platform SDKs. It requires:

* `username`
* `password`
* `endpoint`
* `region`

The username and password are your login credentials for the Sudo Platform Administration Console.

The `endpoint` and `region` are contained in the SDK configuration file that you can download as described in the [Getting Started](https://docs.sudoplatform.com/getting-started#step-2-download-the-sdk-configuration-file) section.

{% hint style="danger" %}
**Do not commit sensitive information, such as your username and password, within your code repository.**
{% endhint %}

### Client Initialization

To instantiate a client in your application, add the following code.

{% tabs %}
{% tab title="Swift" %}

```swift
do {
    let username = // Username obtained from the Sudo Platform Admin Console
    let password = // Password obtained from the Sudo Platform Admin Console
    let simulatorClient = try DefaultSudoVirtualCardsSimulatorClient(
        username: username, 
        password: password
    )
} catch {
    // Handle initialization error. An error might be thrown due to invalid
    // configuration.
}
```

{% endtab %}
{% endtabs %}

## Integrate the Android SDK

The [Android SDK](https://github.com/sudoplatform/sudo-virtual-cards-android) is open source and compatible with Android 6 (API level 23) and above.

Add this line to the dependencies section of the app module's `build.gradle` then synchronize your project with Android Studio.

{% tabs %}
{% tab title="Groovy DSL" %}
{% code title="build.gradle" %}

```groovy
dependencies {
    implementation 'com.sudoplatform:sudovirtualcardssimulator:$latest_version'
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The latest version of the SDK can be found at [SDK Releases](https://docs.sudoplatform.com/guides/virtual-cards-simulator/sdk-releases).
{% endhint %}

{% hint style="info" %}
In order to instantiate a Virtual Cards Simulator client, make sure you have followed the instructions for [Getting Started](https://docs.sudoplatform.com/guides/getting-started)[ ](https://docs.sudoplatform.com/guides/sudos/integrate-the-sudo-sdk)(see Prerequisities above)
{% endhint %}

### **SDK Configuration**

{% hint style="info" %}
Simulator configuration differs from the configuration of the other Sudo Platform SDKs.\
**Please take note of this section.**
{% endhint %}

The Simulator configuration differs from the configuration you will have seen in the other Sudo Platform SDKs. It requires:

* `username`
* `password`
* `endpoint`
* `region`

You can obtain the username and password from the Sudo Platform Administration Console under the Project Settings -> Mobile App Config section. This username and password are your login credentials for the Sudo Platform Administration Console.

The `endpoint` and `region` are contained in the SDK configuration file that you can download as described in the [Getting Started](https://docs.sudoplatform.com/getting-started#step-2-download-the-sdk-configuration-file) section.

{% hint style="danger" %}
**Do not commit sensitive information, such as your username and password, within your code repository.**
{% endhint %}

### **Client Initialization**

To instantiate a client in your application, add the following code.

{% tabs %}
{% tab title="Kotlin" %}

```
val username = // Username obtained from the Sudo Platform Admin Console
val password = // Password obtained from the Sudo Platform Admin Console

val simulatorClient = SudoVirtualCardsSimulatorClient.builder()
    .setContext(appContext)
    .setUsername(username)
    .setPassword(password)
    .build()
```

{% endtab %}
{% endtabs %}

### Threading Considerations

The methods of this API shown in the code samples perform synchronous network requests to the simulator provider. Therefore, these methods should be called with the `Dispatchers.IO` coroutine dispatcher so that the network request is performed on an I/O thread and not on the main thread.

{% hint style="warning" %}
Calling these methods on the main thread may cause a `NetworkOnMainThreadException`
{% endhint %}