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

# Integration Guide

> Integrate Dataspike identity verification into your iOS, Android, and Flutter applications.

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

## Overview

The Dataspike Mobile SDK enables you to embed a full identity verification flow directly into your mobile application. It is built on an embedded Flutter module and supports native iOS, Android, and Flutter integrations.

| Platform | Minimum Version |
| -------- | --------------- |
| Android  | SDK 21+         |
| iOS      | 16.0+           |

<CardGroup cols={3}>
  <Card title="iOS" icon="apple" href="#ios-integration">
    Native Swift integration via CocoaPods
  </Card>

  <Card title="Android" icon="android" href="#android-integration">
    Native Kotlin integration via Gradle
  </Card>

  <Card title="Flutter" icon="flutter" href="#flutter-integration">
    Direct Dart package integration
  </Card>
</CardGroup>

## Prerequisites

Before integrating the SDK, complete these steps:

<Steps>
  <Step title="Install Flutter">
    Install Flutter on your development machine using the [official documentation](https://docs.flutter.dev/install).

    For Android, you can alternatively follow the [AAR-based setup](https://docs.flutter.dev/add-to-app/android/project-setup#depend-on-the-android-archive-aar).
  </Step>

  <Step title="Get your API token">
    Create an account and obtain your API token from the [Dataspike Dashboard](https://dash.dataspike.io/api/settings).
  </Step>

  <Step title="Create a verification">
    Use the [Create Verification](/api-reference/verifications/create-new-verification) endpoint to generate a `verification_url_id` (also referred to as `shortId`).
  </Step>
</Steps>

***

## iOS Integration

<Info>
  **Example project:** [Sample iOS Project Repository](https://github.com/dataspike-io/MobileSDK-Flutter-iOS)
</Info>

### 1. Add the Flutter module

From your iOS project root, add the SDK as a Git submodule:

```bash theme={null}
mkdir -p DataspikeModule
git submodule add -b main https://github.com/dataspike-io/MobileSDK-Flutter.git DataspikeModule/dataspike_module
git submodule update --init --recursive
cd DataspikeModule/dataspike_module/dataspike_module
flutter pub get
cd -
```

### 2. Configure CocoaPods

Update your `Podfile` following the [example Podfile](https://github.com/dataspike-io/MobileSDK-Flutter-iOS/blob/master/Podfile) or the [Flutter Podfile guide](https://docs.flutter.dev/add-to-app/ios/project-setup#update-your-podfile).

The following permission flags are **required** in your `Podfile` build settings:

```ruby theme={null}
'PERMISSION_CAMERA=1',
'PERMISSION_PHOTOS=1',
```

Then install dependencies:

```bash theme={null}
pod install --repo-update
```

<Warning>
  We recommend creating a **separate iOS target** dedicated to verification with its own scheme and Pod configuration. This prevents simulator build failures and keeps your main app target stable. See [Target Configuration](#target--pod-configuration) for details.
</Warning>

### 3. Configure Xcode

**Disable User Script Sandboxing:**

Open **Xcode → Target → Build Settings** and set **User Script Sandboxing** to **NO**.

**Add required permissions** to your `Info.plist`:

| Key                              | Required   |
| -------------------------------- | ---------- |
| `NSCameraUsageDescription`       | Always     |
| `NSPhotoLibraryUsageDescription` | Always     |
| `NSMotionUsageDescription`       | Always     |
| `NSLocalNetworkUsageDescription` | Debug only |
| `NSBonjourServices`              | Debug only |

For `NSBonjourServices`, add the values `_dartVmService._tcp` and `_googlecast._tcp`.

### 4. Start the verification flow

```swift theme={null}
channel.setMethodCallHandler { call, result in
  if call.method == "onVerificationCompleted" {
    if let args = call.arguments as? [String: String] {
      if args["status"] == "Completed" {
        flutterVC.dismiss(animated: true, completion: nil)
      }
    }
    result(nil)
  } else {
    result(FlutterMethodNotImplemented)
  }
}

present(flutterVC, animated: true) {
  channel.invokeMethod("startDataspikeFlow", arguments: [
    "dsApiToken": "your_token",
    "shortId": "your_short_id",
    "isDebug": true // set to false for production
  ])
}
```

For a complete implementation, see the [example ViewController](https://github.com/dataspike-io/MobileSDK-Flutter-iOS/blob/master/flutteriosexample/SomeViewController.swift) or the [Flutter engine guide](https://docs.flutter.dev/add-to-app/ios/add-flutter-screen#create-a-flutterengine).

### 5. Update the submodule

To update the SDK to a specific version:

```bash theme={null}
cd DataspikeModule/dataspike_module
git fetch
git checkout <commit_or_tag>
cd -
git add DataspikeModule/dataspike_module
git commit -m "Update DataspikeModule"
```

***

## Android Integration

<Info>
  **Example project:** [Sample Android Project Repository](https://github.com/dataspike-io/MobileSDK-Flutter-Android)
</Info>

### 1. Add the Flutter module

From your Android project root:

```bash theme={null}
mkdir -p DataspikeModule
git submodule add -b main https://github.com/dataspike-io/MobileSDK-Flutter.git DataspikeModule/dataspike_module
git submodule update --init --recursive
cd DataspikeModule/dataspike_module/dataspike_module
flutter pub get
cd -
```

### 2. Configure settings.gradle

Update your `settings.gradle.kts` to include the Flutter module:

```kotlin theme={null}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "YourProjectName"
include(":app")

val filePath = settingsDir.toString() +
  "/DataspikeModule/dataspike_module/dataspike_module/.android/include_flutter.groovy"
apply(from = File(filePath))
```

See the [example settings.gradle](https://github.com/dataspike-io/MobileSDK-Flutter-Android/blob/master/settings.gradle.kts) or the [Flutter guide](https://docs.flutter.dev/add-to-app/android/project-setup#updating-settings-gradle).

### 3. Update build.gradle

Follow the [example build.gradle](https://github.com/dataspike-io/MobileSDK-Flutter-Android/blob/master/app/build.gradle.kts) or the [Flutter guide](https://docs.flutter.dev/add-to-app/android/project-setup#updating-appbuild-gradle).

### 4. Add permissions

Add these permissions to your `AndroidManifest.xml`:

```xml theme={null}
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>
```

### 5. Start the verification flow

```kotlin theme={null}
channel.setMethodCallHandler { call, result ->
  if (call.method == "onVerificationCompleted") {
    val args = call.arguments as? Map<*, *>
    val status = args?.get("status")
    if (status == "Completed") {
      // Handle completion
    }
    result.success(null)
  } else {
    result.notImplemented()
  }
}

channel.invokeMethod(
  "startDataspikeFlow",
  mapOf(
    "dsApiToken" to "your_token",
    "shortId" to "your_short_id",
    "isDebug" to true // set to false for production
  )
)
```

For a complete implementation, see the [example Activity](https://github.com/dataspike-io/MobileSDK-Flutter-Android/blob/master/app/src/main/java/com/example/implementationflutterexample/MainActivity.kt) or the Flutter guides for [Flutter Screen](https://docs.flutter.dev/add-to-app/android/add-flutter-screen#add-a-normal-flutter-screen) and [Flutter Fragment](https://docs.flutter.dev/add-to-app/android/add-flutter-fragment#add-a-flutterfragment-to-an-activity-with-a-new-flutterengine).

<Warning>
  Flutter supports AOT builds only for `armeabi-v7a`, `arm64-v8a`, and `x86_64`. If your app supports additional ABIs (e.g. `mips`, `x86`), you may encounter integration issues. See the [Flutter ABI documentation](https://docs.flutter.dev/deployment/android#android-app-bundles-and-apk-splitting).
</Warning>

***

## Flutter Integration

<Info>
  **Example projects:** [In-repo example](https://github.com/dataspike-io/MobileSDK-Flutter/blob/main/example/lib/main.dart) · [Standalone example](https://github.com/dataspike-io/MobileSDK-Flutter-App)
</Info>

### 1. Add the dependency

Add the SDK to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  flutter:
    sdk: flutter
  dataspikemobilesdk:
    git:
      url: https://github.com/dataspike-io/MobileSDK-Flutter
      ref: 1.0.0
```

### 2. Configure platform permissions

<Tabs>
  <Tab title="iOS">
    Add to your `Info.plist`:

    * `NSCameraUsageDescription`
    * `NSPhotoLibraryUsageDescription`
    * `NSMotionUsageDescription`
    * `NSLocalNetworkUsageDescription` (Debug only)

    Add to your `Podfile` build settings ([example](https://github.com/dataspike-io/MobileSDK-Flutter/blob/main/example/ios/Podfile)):

    ```ruby theme={null}
    'PERMISSION_CAMERA=1',
    'PERMISSION_PHOTOS=1',
    ```
  </Tab>

  <Tab title="Android">
    Add to your `AndroidManifest.xml`:

    ```xml theme={null}
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
    <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>
    ```
  </Tab>
</Tabs>

### 3. Start the verification flow

```dart theme={null}
import 'package:dataspikemobilesdk/dataspikemobilesdk.dart';

final _dataspikemobilesdkPlugin = Dataspikemobilesdk();

_dataspikemobilesdkPlugin.startDataspikeFlow(
  context: context,
  dependencies: .new(
    isDebug: true, // set to false for production
    dsApiToken: "your_token",
    shortId: "your_short_id",
  ),
  callback: (status) {
    // Handle verification result
  },
);
```

<Note>
  On Apple Silicon machines, Flutter-based integration may require running Xcode under Rosetta for proper testing and dependency compatibility.
</Note>

***

## Verification Statuses

The `onVerificationCompleted` callback returns one of the following statuses:

| Status      | Description                                         |
| ----------- | --------------------------------------------------- |
| `Completed` | The verification flow finished successfully.        |
| `Expired`   | The verification session expired before completion. |
| `Failed`    | The verification flow encountered an error.         |

***

## Known Limitations

<AccordionGroup>
  <Accordion title="Device-only verification (iOS)">
    Verification is fully supported **only on real devices**. iOS simulators may not work correctly. Simulator support improvements are planned for future releases.
  </Accordion>

  <Accordion title="Slow image loading in Debug builds">
    In Debug configuration, image loading during verification may be significantly slower. Always test the verification flow using the **Release** build configuration for accurate performance.
  </Accordion>

  <Accordion title="Target & Pod configuration (iOS)">
    To prevent simulator build failures, create a **separate iOS target** for verification:

    ```ruby theme={null}
    target 'MainApp' do
      # Regular pods only
    end

    target 'MainAppVerification' do
      pod 'DataSpikeMobileSDK'
    end
    ```

    This keeps device-only dependencies isolated from your main app target and CI pipelines.
  </Accordion>

  <Accordion title="Android ABI support">
    Flutter supports AOT builds only for `armeabi-v7a`, `arm64-v8a`, and `x86_64`. Remove unsupported ABIs like `mips` or `x86` from your project configuration.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="LLDB initialization issues (iOS)">
    If Flutter debugging doesn't work correctly, set up the LLDB init file following the [official guide](https://docs.flutter.dev/add-to-app/ios/project-setup#set-lldb-init-file).

    You may also need to set the iOS platform version in the Flutter module podspec:

    ```ruby theme={null}
    s.platform = :ios, '16.0'
    ```
  </Accordion>

  <Accordion title="Local network permission issues (iOS)">
    Flutter tools require local network access for the Dart VM Service. Ensure the required permissions are added to your `Info.plist` and allowed in iOS system settings. See the [official documentation](https://docs.flutter.dev/add-to-app/ios/project-setup#set-local-network-privacy-permissions).
  </Accordion>

  <Accordion title="Apple Silicon build issues">
    On Apple Silicon Macs, you may encounter simulator architecture issues. Follow the [official guide](https://docs.flutter.dev/add-to-app/ios/project-setup#mitigate-known-issue-with-apple-silicon-macs) to exclude `arm64` for iOS simulators or adjust CocoaPods build settings.
  </Accordion>
</AccordionGroup>