> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudo.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Native SDK

> Integrate the Sudo Cloud Card iOS Native SDK for provisioning, token management, QR generation, and local transaction access.

## Overview

The Cloud Card iOS SDK provides APIs for:

* Card provisioning and registration
* Retrieving locally stored cards
* Generating EMV QR codes
* Reading token inventory and usage summaries
* Accessing locally cached transactions

The native entry point exposed by the SDK is `CloudCardWrapper`.

## Installation

`CloudCard` is distributed as an `XCFramework` through Sudo Africa's protected artifact repository.

### Requirements

* iOS 13.0+
* Xcode 15+
* CocoaPods
* Physical iPhone recommended for payment testing

### SDK Repository Authentication

You need repository credentials from Sudo Africa before installation.

```bash theme={null}
export SUDO_USER="your_sdk_username"
export SUDO_PASSWORD="your_sdk_password"
```

Or load them from `.env`:

```bash theme={null}
export $(grep -v '^#' .env | xargs)
```

Use a temporary `.netrc` file when installing:

```bash theme={null}
TMPHOME=$(mktemp -d)
trap 'rm -rf "$TMPHOME"' EXIT
export HOME="$TMPHOME"
cat > "$HOME/.netrc" <<EOF_NETRC
machine sdk.sudo.africa
login $SUDO_USER
password $SUDO_PASSWORD
EOF_NETRC
chmod 600 "$HOME/.netrc"
cd ios && pod install
```

<Info>
  Do not commit `.env`, `.netrc`, or SDK credentials to source control.
</Info>

## Environments

The SDK supports two environments:

* `true` for sandbox
* `false` for production

Your SDK environment must match the backend environment issuing the provisioning payload.

## Initialization

Initialize the SDK once during app startup before calling any other Cloud Card API.

```swift theme={null}
import CloudCard

CloudCardWrapper.initializeSDK(true)
```

Use `true` for sandbox and `false` for production.

## Register a Card

Provisioning data must come from your backend after the user is authenticated. The client app should not generate provisioning credentials locally.

Typical payload values include:

* `walletId`
* `accountId`
* `paymentAppInstanceId`
* `secret`
* `jwtToken`

Example:

```swift theme={null}
import CloudCard

let data = WalletRequestIOS()
data.accountId = accountId
data.tokenUniqueReference = accountId
data.paymentAppInstanceId = paymentAppInstanceId
data.secret = secret
data.keyNumber = 0
data.walletId = walletId
data.jwtToken = jwt

let result = await CloudCardWrapper.registerCard(data)
```

Successful registration stores the provisioned card locally on the device.

## Retrieve Cards

```swift theme={null}
if let fetched = CloudCardWrapper.getCards() as? [Any] {
    // Map results to your UI model
}
```

Filter active cards before displaying them to users.

## Token Summary

Use token summary to monitor the current token balance and refresh state after provisioning or payment activity.

```swift theme={null}
if let summaryResult = CloudCardWrapper.getTokenSummary() as? [String: Any] {
    let totalTokens = summaryResult["totalTokens"] as? Int
    let tokensBalance = summaryResult["tokensBalance"] as? Int
}
```

## Retrieve Saved Transactions

```swift theme={null}
let raw = CloudCardWrapper.getSavedTransactions()
```

Saved transaction records typically include:

* ATC
* Amount
* Timestamp

## Generate EMV QR

```swift theme={null}
if let result = CloudCardWrapper.getEmvQr(
    amount,
    foregroundColorHex: "#000000",
    backgroundColorHex: "#FFFFFF"
),
let status = result["status"] as? String,
status == "SUCCESS",
let qrImageResult = result["data"] as? UIImage {
    // Render QR image
}
```

The QR API supports dynamic amounts and custom foreground or background colors.

## Common Issues

### Authentication Failure During Installation

Check:

* `SUDO_USER` is set
* `SUDO_PASSWORD` is set
* Credentials are valid
* `.netrc` is configured correctly

### Works on Device but Fails on Simulator

If the XCFramework only includes `ios-arm64`, simulator builds will fail. Use a physical iPhone or request a simulator-compatible XCFramework.

### Registration Succeeds but No Cards Are Returned

Verify:

* SDK environment matches backend environment
* `walletId` and `accountId` are correct
* registration returned success
* stored cards are active

### QR Generation Fails

Check:

* there is an active card on the device
* token inventory is not depleted
* the amount format is valid
* SDK environment matches the provisioning environment

## Best Practices

* Initialize the SDK once during app startup
* Use a stable device identifier for `paymentAppInstanceId`
* Fetch provisioning data from a secure backend endpoint
* Avoid logging secrets or JWTs in production
* Refresh cards and token summary after provisioning or payment events