App 启动
   │
   ▼
Call OSLCardApp.setup() (configure the environment and initialize risk-control capability)
   │
   ▼
Your backend retrieves a single-use accessToken
   │
   ▼
Call OSLCardApp.bindCard()
   │
   ▼
The SDK loads and validates accessToken
   │
   ├── accessToken validation fails ──► onTokenInvalid (terminal callback); end the flow
   │
   ▼
Display the card-binding screen (the user enters payment-card details)
   │
   ├── API error ──► SDK Toast, or onToastShow when suppression applies
   │
   ├── Binding fails / user exits ──► onBindFailure (terminal callback); end the flow
   │
   ▼
Card binding succeeds
   │
   ▼
onBindSuccess(cardId) (terminal callback); end the flow

Vendor/OSL_Card_SDK/OSL_Card_SDK.xcframework
Vendor/OSL_Card_SDK/OSLPayRiskSDK.xcframework

platform :ios, '14.0'
inhibit_all_warnings!
source 'https://github.com/CocoaPods/Specs.git'

use_frameworks! :linkage => :dynamic

pre_install do |installer|
  Pod::Installer::Xcode::TargetValidator
    .send(:define_method, :verify_no_static_framework_transitive_dependencies) {}
end

target 'YourAppTarget' do
  pod 'ForterSDK', :git => 'https://bitbucket.org/forter-mobile/forter-ios-sdk.git', :tag => '3.0.4'
  pod 'HandyJSON', :git => 'https://github.com/hxm705/HandyJSON.git', :commit => 'de8a7126d2270da55cea3cb45dadffcfd002dbbe'
  pod 'IQKeyboardManager', '6.5.3'
  pod 'CocoaLumberjack', '3.8.1'
  pod 'RxSwift', '6.5.0'
  pod 'ReactiveObjC', '3.1.1'
  pod 'Masonry', '1.1.0'
  pod 'SnapKit', '5.6.0'
  pod 'MMKV', '1.2.11'
  pod 'Kingfisher', '7.8.1'
  pod 'lottie-ios', '3.3.0'
  pod 'LYEmptyView', '1.3.1'
  pod 'KingfisherSVG', '1.0.0'
  pod 'Risk', '3.0.4'
  pod 'QMUIKit', '4.8.0'
  pod 'Moya', '15.0.0'
  pod 'Alamofire', '5.10.2'
  pod 'SwiftyJSON', '5.0.2'
  pod 'DeviceKit', '5.7.0'
  pod 'FingerprintJS', '1.6.0'
  pod 'SwiftyRSA', '1.7.0'
end

post_install do |installer|
  installer.generated_projects.each do |project|
    project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '14.0'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end

  installer.aggregate_targets.each do |aggregate_target|
    aggregate_target.user_project.native_targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
      end
    end
    aggregate_target.user_project.save
  end
end

Replace `YourAppTarget` with your actual app target, then run:

```bash
pod install

import UIKit
import OSL_Card_SDK

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        OSLCardApp.setup(
            openSandBoxEnv: true,
            with: launchOptions,
            disableTrack: true
        )
        return true
    }
}

Parameter reference:

| Parameter        | Required | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `openSandBoxEnv` |    No    | Whether to use Sandbox. Defaults to `false` (Production). Pass `true` during development and `false` in production. |
| `launchOptions`  |    No    | Launch options received by `AppDelegate`. Pass them through unchanged.|
| `disableTrack`   |    No    | Whether to disable SDK analytics. Defaults to `false`. When `true`, the SDK does not initialize or report analytics.|

OSLCardApp.bindCard(...)

import OSL_Card_SDK

OSLCardApp.bindCard(
    accessToken: accessToken,       // Required; single-use only
    businessType: "BUY",           // Optional; defaults to BUY
    language: "zh_CN",             // Optional; the SDK selects a language when omitted
    theme: "light",                // Optional: light / dark
    phone: false,                   // Optional; whether to show the phone-number field
    suppressedErrorCodes: nil,      // Optional; error codes to suppress
    suppressErrors: false,          // Optional; whether to suppress all errors
    onTokenInvalid: { errorCode, errorMessage in
        // accessToken validation failure (terminal)
    },
    onBindSuccess: { cardId in
        // Card-binding success (terminal)
    },
    onBindFailure: { errorCode, errorMessage in
        // Binding failure or user exit (terminal)
    },
    onToastShow: { errorCode, errorMessage in
        // Immediate callback for a suppressed error; handle it in your app
    }
)

Minimum invocation:

```swift
OSLCardApp.bindCard(
    accessToken: accessToken,
     onBindSuccess: { cardId in
        print("Bind card success: \(cardId)")
    }
)

> `accessToken` is a sensitive credential. Do not write it to logs, persistent storage, or source control. Each token is single-use; obtain a new token before calling `bindCard` again.

## 

| Parameter            | Required | Description |
| -------------------- | -------- | ------------|
> `accessToken` is a sensitive credential. Do not write it to logs, persistent storage, or source control. Each token is single-use; obtain a new token before calling `bindCard` again.

## 3. Parameter reference

| Parameter            | Required | Description |
| -------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `accessToken`        | **Yes**  | User-identity validation token. It is single-use; obtain a new token before the next `bindCard` call. |
| businessType         | No       | Business type. Defaults to BUY; available values depend on the services enabled for your merchant account, such as BUY and SELL. |
| language             | No       | SDK display language, for example zh_CN or en_US. See Supported SDK languages for valid values. |
| theme                | No       | UI theme. Valid values are light and dark. When nil, the SDK uses its default theme. |
| phone                | No       | Whether to display the phone-number field on the card-binding screen. Defaults to false. |
| suppressedErrorCodes | No       | List of error codes to suppress. When a code matches, the SDK does not display a Toast and invokes onToastShow. |
| suppressErrors       | No       | Whether to suppress all errors. Defaults to false. When true, the SDK does not display error Toasts and invokes onToastShow. |
| onTokenInvalid       | No       | Callback for accessToken validation failure. Returns errorCode and errorMessage (terminal callback). |
| onBindSuccess        | No       | Callback for successful card binding. Returns the bound cardId (terminal callback). |
| onBindFailure        | No       | Callback for binding failure or user exit. Returns errorCode and errorMessage (terminal callback). |
| onToastShow          | No       | Immediate callback for suppressed errors; handle the error message in your app. |

onBindFailure: { errorCode, errorMessage in
    Task { @MainActor in
        // Update UI state
    }
}

| Scenario                                  | SDK behavior                                                   |
| ----------------------------------------- | -------------------------------------------------------------- |
| No suppression configured                 | The SDK displays a Toast with the error message.               |
| Error code matches `suppressedErrorCodes` | The SDK does not display a Toast and invokes `onToastShow`.    |
| `suppressErrors = true`                   | The SDK suppresses all error Toasts and invokes `onToastShow`. |