# Getting Started with CaptureSDK

Platform-specific setup requirements for Socket Mobile CaptureSDK integration. Covers Android (Gradle dependencies, AndroidManifest permissions), iOS, Windows, React Native, Flutter, and .NET MAUI configuration. Includes AppKey registration on Socket Mobile developer portal.

## Requirements

The Socket Mobile CaptureSDK is the interface between your applications and our hardware scanners and our camera based scanning solution. It is compatible with Bluetooth Classic and Bluetooth Low Energy (BLE) for our scanners and contactless reader/writer products (such as the Socket Mobile D600, S550, S370, S320, S721, S741 and M963).

For applications that need to work with barcode scanners, make sure the following requirements are met:

## Android

The Android CaptureSDK aims to make it as simple as possible to add scanning functionality into an Android application. It hides the complexity of the Android activity lifecycle by hooking into it. If you prefer more direct control over the CaptureClient instance, refer to the [Plain Java SDK](#plain-java-sdk-without-capture-android) section below.

> **Note**
>
> The Socket Mobile Companion app is required and can be downloaded from the <a href="https://play.google.com/store/apps/details?id=com.socketmobile.companion">Google Play Store</a>.

## AndroidManifest.xml Requirements

Your application's **AndroidManifest.xml** *must* include the AppKey and Developer ID metadata inside the `<application>` tag:

### App Key

Your application will need a SocketMobile AppKey. Follow the link to [create an AppKey](https://www.socketmobile.dev/application-details/appkey-registration). AppKeys can be generated online and at no additional cost beyond the nominal registration fee. The AppKey is validated by the CaptureSDK library on the device — no internet connection is required.

```xml
<meta-data
    android:name="com.socketmobile.capture.APP_KEY"
    android:value="[YOUR ANDROID APP KEY]"/>
<meta-data
    android:name="com.socketmobile.capture.DEVELOPER_ID"
    android:value="[YOUR DEVELOPER ID]"/>
```

## Network Security Config

> **Note**
>
> If your app targets Android 27 or lesser, this section can be ignored. For Android 28 (Pie) and later, you must enable cleartext traffic to localhost so that CaptureSDK can communicate with the Socket Mobile Companion app.

- Add the **networkSecurityConfig** attribute to the `<application>` tag in your **AndroidManifest.xml**:

```xml
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
```

- If you do not already have a network security configuration file, create **res/xml/network_security_config.xml** with the following content:

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <base-config cleartextTrafficPermitted="false" />
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="false">localhost</domain>
    <domain includeSubdomains="false">127.0.0.1</domain>
  </domain-config>
</network-security-config>
```

## build.gradle Configuration

Your application's **build.gradle** *must* include the Socket Mobile Maven repository and the CaptureSDK dependency:

```groovy
repositories {
    mavenCentral()
    maven {
        url "https://bin.socketmobile.com/repo/releases"
    }
}

dependencies {
    implementation 'com.socketmobile:capture-android:2.1.2'
}
```

## Additional Requirements

- The scanner needs to be paired with your devices in Application Mode. This can be done using the [Socket Mobile Companion app](https://play.google.com/store/apps/details?id=com.socketmobile.companion) (recommended), which can be downloaded from the Google Play Store.

- Try our sample app [HelloCapture](https://github.com/SocketMobile/samples-android) on GitHub.

## Plain Java SDK (without capture-android)

The `capture-android` library described above is the recommended integration for most applications. The plain Java SDK (`com.socketmobile:capture`) can also be used directly, without `capture-android`. It is a good candidate when the CaptureSDK lives in a layer of your architecture that does not have an Activity, or does not follow the regular Android application lifecycle — for example a background service or a shared business layer.

With this path your application talks to `CaptureClient` directly and receives events through plain listener interfaces instead of EventBus.

Replace the `capture-android` dependency with the plain `capture` module (EventBus is not required for this integration path):

```groovy
dependencies {
    implementation 'com.socketmobile:capture:2.1.2'
}
```

The AndroidManifest.xml and Network Security Config requirements above still apply, but the AppKey is passed in code instead of the manifest metadata.

See the [Plain Java SDK](/docs/appendix/plain-java-sdk) appendix for the initialization and events code.

## iOS

> **Warning**
>
> From version 2.0 and later we have changed the way CaptureSDK on iOS is connecting to our Bluetooth Low Energy devices (S721, S741, S320, S370, S550, M963).

## Info.plist Requirements

- Your application's **Info.plist** *must* have the key **LSApplicationQueriesSchemes** (Queried URL Schemes) with a new item: **sktcompanion** (in lower case).

- Your application's **Info.plist** *must* have the key **NSCameraUsageDescription** with a string value explaining to the user how the app uses the camera for camera scanning purpose.

- Your application's **Info.plist** *must* have the key **UISupportedExternalAccessoryProtocols** (Supported External Protocol) with a new item: **com.socketmobile.chs** (in lower case).

- Your application's **Info.plist** *must* have the key **NSBluetoothAlwaysUsageDescription** with a string value explaining to the user how your application uses this feature. This is an iOS/Apple requirement for applications that use the CoreBluetooth framework. Without it, your application will crash with a message in the Xcode console explaining that you must add the description key.

- Your application's **Info.plist** *must* have the key **CFBundleAllowMixedLocalizations** (Localized resources can be mixed) to **YES**.

## Additional Requirements

- Your application will need a SocketMobile AppKey. Follow the link to [create an AppKey](/manage-apps). AppKeys can be generated online and at no additional cost beyond the nominal registration fee. The AppKey is validated by the CaptureSDK library on the device, no internet connection is required. Note: You don't need to create your own AppKey to compile and run the sample apps.

- You can install CaptureSDK through [Swift Package Manager](https://github.com/SocketMobile/swift-package-capturesdk).

- The scanner needs to be paired with your devices in Application Mode. This can be done using [Socket Mobile Companion app](https://apps.apple.com/app/socket-mobile-companion/id1175638950) (recommended), which can be downloaded from the App Store.

- Try our sample app [Single Entry in Swift](https://github.com/SocketMobile/capturesingleentryswift-ios) on Github.

## React Native

> **Note**
>
> Since version 2.0, the React Native CaptureSDK fully supports the React Native new architecture and introduces a new <strong>CaptureHelper</strong>, a high-level lifecycle manager replacing the manual CaptureRn + onCaptureEvent pattern.

## Installation

Using yarn:

```bash
yarn add react-native-capture
```

Using npm:

```bash
npm install --save react-native-capture
```

## iOS Configuration

Your application's **Info.plist** requires the following keys:

- **LSApplicationQueriesSchemes** (Queried URL Schemes) with a new item: **sktcompanion** (in lower case).

- **NSCameraUsageDescription** with a string value explaining to the user how the app uses the camera for camera scanning purpose.

- **UISupportedExternalAccessoryProtocols** (Supported External Protocol) with a new item: **com.socketmobile.chs** (in lower case).

- **NSBluetoothAlwaysUsageDescription** with a string value explaining to the user how your application uses this feature. This is an iOS/Apple requirement for applications that use the CoreBluetooth framework. Without it, your application will crash with a message in the Xcode console explaining that you must add the description key.

- **CFBundleAllowMixedLocalizations** (Localized resources can be mixed) to **YES**.

## Android Configuration

> **Note**
>
> The Socket Mobile Companion app is required and can be downloaded from the <a href="https://play.google.com/store/apps/details?id=com.socketmobile.companion">Google Play Store</a>.

### AndroidManifest.xml Requirements

Add the following permissions to your **AndroidManifest.xml**:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
```

Your application's **AndroidManifest.xml** *must* include the AppKey and Developer ID metadata inside the **application** tag:

```xml
<meta-data
    android:name="com.socketmobile.capture.APP_KEY"
    android:value="[YOUR ANDROID APP KEY]"/>
<meta-data
    android:name="com.socketmobile.capture.DEVELOPER_ID"
    android:value="[YOUR DEVELOPER ID]"/>
```

Add the following before the closing **manifest** tag to allow communication with the Companion app:

```xml
...
<queries>
  <package android:name="com.socketmobile.companion"/>
</queries>

</manifest>
```

### Network Security Configuration

> **Note**
>
> If your app targets Android 27 or lesser, this section can be ignored. For Android 28 and later, you must enable cleartext traffic to localhost so that CaptureSDK can communicate with the Socket Mobile Companion app.

- Add the **networkSecurityConfig** attribute to the `<application>` tag in your **AndroidManifest.xml**:

```xml
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
```

- If you do not already have a network security configuration file, create **android/app/src/main/res/xml/network_security_config.xml** with the following content:

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <base-config cleartextTrafficPermitted="false" />
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="false">localhost</domain>
    <domain includeSubdomains="false">127.0.0.1</domain>
  </domain-config>
</network-security-config>
```

### Gradle Configuration

Add the Socket Mobile repository to your **android/build.gradle**:

```groovy
allprojects {
    repositories {
        maven {
            url "https://bin.socketmobile.com/repo/releases"
        }
    }
}
```

Add packaging options to your **app/build.gradle**:

```groovy
android {
    packagingOptions {
        pickFirst '/lib/arm64-v8a/libc++_shared.so'
        pickFirst '/lib/armeabi-v7a/libc++_shared.so'
    }
}
```

## Additional Requirements

- Your application will need a SocketMobile AppKey. Follow the link to [create an AppKey](/manage-apps). AppKeys can be generated online and at no additional cost beyond the nominal registration fee. The AppKey is validated by the CaptureSDK library on the device, no internet connection is required. Note: You don't need to create your own AppKey to compile and run the sample apps.

- The scanner needs to be paired with your devices in Application Mode. This can be done using the Socket Mobile Companion app ([iOS](https://apps.apple.com/app/socket-mobile-companion/id1175638950) | [Android](https://play.google.com/store/apps/details?id=com.socketmobile.companion)).

- Try our sample app [React Native CaptureSDK](https://github.com/SocketMobile/react-native-capture) on GitHub for the full API reference, quick start code, and migration guide from v1.x.

## Flutter

> **Note**
>
> Since version 2.0, the Flutter CaptureSDK adds support for Bluetooth LE devices such as our brand new barcode scanner S721. Users can either install the Socket Mobile Companion app for adding Bluetooth LE devices, or implement a custom discovery UI using the SDK.

## Installation

Add the CaptureSDK Flutter plugin to your **pubspec.yaml**:

```yaml
dependencies:
  flutter:
    sdk: flutter
  capturesdk_flutter: ^2.1.8
```

Then run the following command to install the dependency:

```bash
flutter pub get
```

## iOS Configuration

### Swift Package Manager

The native iOS CaptureSDK Flutter plugin is now distributed through Swift Package Manager (SPM) and requires Flutter 3.44 or later. CocoaPods is no longer needed: when you run your app, Flutter adds the SPM integration to your Xcode project and downloads the plugin's Swift packages.

If SPM was previously disabled on your machine, enable it again:

```bash
flutter config --enable-swift-package-manager
```

Your app's iOS deployment target must be **15.0** or later. In Xcode, select the Runner target, open **General** and set **Minimum Deployments** to **15.0**.

### Migrating from CocoaPods

If your app was set up with CocoaPods, remove it before running the app with SPM:

1. Run the following from your app's **ios** directory:

   ```bash
   pod deintegrate
   ```

2. Delete **Podfile**, **Podfile.lock** and the **Pods/** directory.
3. Remove the **Pods-Runner** `#include` lines from **ios/Flutter/Debug.xcconfig** and **ios/Flutter/Release.xcconfig**.
4. Run `flutter run`. Flutter adds the SPM integration to your Xcode project.

> **Warning**
>
> Flutter falls back to CocoaPods if any of your app's plugins do not support SPM yet. Check that all your plugins support SPM before removing CocoaPods.

### Info.plist

Your application's **Info.plist** requires the following keys:

- **LSApplicationQueriesSchemes** (Queried URL Schemes) with a new item: **sktcompanion** (in lower case).

- **NSCameraUsageDescription** with a string value explaining to the user how the app uses the camera for camera scanning purpose.

- **UISupportedExternalAccessoryProtocols** (Supported External Protocol) with a new item: **com.socketmobile.chs** (in lower case).

- **NSBluetoothAlwaysUsageDescription** with a string value explaining to the user how your application uses this feature. This is an iOS/Apple requirement for applications that use the CoreBluetooth framework. Without it, your application will crash with a message in the Xcode console explaining that you must add the description key.

- **CFBundleAllowMixedLocalizations** (Localized resources can be mixed) to **YES**.

### Xcode Build Settings

Open the project's iOS directory in Xcode. Select the Runner target, navigate to **Build Settings**, search for "module" and set **Allow Non-modular Includes in Framework Modules** to **Yes**.

## Android Configuration

> **Note**
>
> The Socket Mobile Companion app is required and can be downloaded from the <a href="https://play.google.com/store/apps/details?id=com.socketmobile.companion">Google Play Store</a>.

### MainActivity.java

Register the CaptureSDK as a plugin in your **MainActivity.java**:

```java
package com.example.example;

import com.capturesdk_flutter.CaptureModule;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;

public class MainActivity extends FlutterActivity {
    @Override
    public void configureFlutterEngine(FlutterEngine flutterEngine) {
        flutterEngine.getPlugins().add(new CaptureModule(getApplicationContext()));
    }
}
```

### AndroidManifest.xml Requirements

Add the following permissions to your **AndroidManifest.xml**:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
```

Your application's **AndroidManifest.xml** *must* include the AppKey and Developer ID metadata inside the **application** tag:

```xml
<meta-data
    android:name="com.socketmobile.capture.APP_KEY"
    android:value="[YOUR ANDROID APP KEY]"/>
<meta-data
    android:name="com.socketmobile.capture.DEVELOPER_ID"
    android:value="[YOUR DEVELOPER ID]"/>
```

Add the following before the closing **manifest** tag to allow communication with the Companion app:

```xml
...
<queries>
  <package android:name="com.socketmobile.companion"/>
</queries>

</manifest>
```

### build.gradle

Add the following to your app-level **build.gradle** to disable minification and resource shrinking:

```groovy
buildTypes {
    release {
        minifyEnabled false
        shrinkResources false
        signingConfig = signingConfigs.debug
    }
}
```

### Network Security Configuration

> **Note**
>
> If your app targets Android 27 or lesser, this section can be ignored. For Android 28 and later, you must enable cleartext traffic to localhost so that CaptureSDK can communicate with the Socket Mobile Companion app.

- Add the **networkSecurityConfig** attribute to the **application** tag in your **AndroidManifest.xml**:

```xml
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
```

- If you do not already have a network security configuration file, create **android/app/src/main/res/xml/network_security_config.xml** with the following content:

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <base-config cleartextTrafficPermitted="false" />
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="false">localhost</domain>
    <domain includeSubdomains="false">127.0.0.1</domain>
  </domain-config>
</network-security-config>
```

## Additional Requirements

- Your application will need a SocketMobile AppKey. Follow the link to [create an AppKey](/manage-apps). AppKeys can be generated online and at no additional cost beyond the nominal registration fee. The AppKey is validated by the CaptureSDK library on the device, no internet connection is required. Note: You don't need to create your own AppKey to compile and run the sample apps.

- For Flutter, you need to register your app separately for each platform (iOS and Android) on the developer portal. Include both platform credentials in the same **AppInfo** instance.

- The scanner needs to be paired with your devices in Application Mode. This can be done using the Socket Mobile Companion app ([iOS](https://apps.apple.com/app/socket-mobile-companion/id1175638950) | [Android](https://play.google.com/store/apps/details?id=com.socketmobile.companion)).

- Try our sample app [Flutter CaptureSDK Sample](https://github.com/SocketMobile/capture_flutter_sdk_sample) on GitHub.

## MAUI

.NET MAUI allows you to target iOS, Android and Windows platforms through a single C# codebase. The **SocketMobile.Capture** NuGet package provides CaptureSDK support for all three platforms. The Newtonsoft JSON dependency installs automatically with the package.

## NuGet Package Installation

- Install the **SocketMobile.Capture** NuGet package from the NuGet Package Manager or via the .NET CLI:

```bash
dotnet add package SocketMobile.Capture
```

## iOS Configuration

Your MAUI project's **Info.plist** (located in **Platforms/iOS/**) *must* include the following keys:

- Your application's **Info.plist** *must* have the key **LSApplicationQueriesSchemes** (Queried URL Schemes) with a new item: **sktcompanion** (in lower case).

- Your application's **Info.plist** *must* have the key **NSCameraUsageDescription** with a string value explaining to the user how the app uses the camera for camera scanning purpose.

- Your application's **Info.plist** *must* have the key **UISupportedExternalAccessoryProtocols** (Supported External Protocol) with a new item: **com.socketmobile.chs** (in lower case).

- Your application's **Info.plist** *must* have the key **NSBluetoothAlwaysUsageDescription** with a string value explaining to the user how your application uses this feature. This is an iOS/Apple requirement for applications that use the CoreBluetooth framework. Without it, your application will crash with a message in the console explaining that you must add the description key.

- Your application's **Info.plist** *must* have the key **CFBundleAllowMixedLocalizations** (Localized resources can be mixed) to **YES**.

## Android Configuration

> **Note**
>
> The Socket Mobile Companion app is required and can be downloaded from the <a href="https://play.google.com/store/apps/details?id=com.socketmobile.companion">Google Play Store</a>.

Your MAUI project's **AndroidManifest.xml** (located in **Platforms/Android/**) *must* include the AppKey and Developer ID metadata inside the `<application>` tag:

```xml
<meta-data
    android:name="com.socketmobile.capture.APP_KEY"
    android:value="[YOUR ANDROID APP KEY]"/>
<meta-data
    android:name="com.socketmobile.capture.DEVELOPER_ID"
    android:value="[YOUR DEVELOPER ID]"/>
```

> **Warning**
>
> For Android 28 (Pie) and later, a network security configuration is required to allow CaptureSDK to communicate with the Socket Mobile Companion app over localhost.

- Add the `networkSecurityConfig` attribute to the `<application>` tag in your **AndroidManifest.xml**:

```xml
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
```

- Create the file **Platforms/Android/Resources/xml/network_security_config.xml** with the following content:

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <base-config cleartextTrafficPermitted="false" />
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="false">localhost</domain>
    <domain includeSubdomains="false">127.0.0.1</domain>
  </domain-config>
</network-security-config>
```

## Windows Configuration

- The **Socket Mobile Companion** software must be installed on the host PC. Download it from [GitHub](https://github.com/SocketMobile/companion-windows/releases).

## Additional Requirements

- Your application will need a SocketMobile AppKey. Follow the link to [create an AppKey](/manage-apps). AppKeys can be generated online and at no additional cost beyond the nominal registration fee. The AppKey is validated by the CaptureSDK library on the device, no internet connection is required. Note: You don't need to create your own AppKey to compile and run the sample apps.

- The scanner needs to be paired with your devices in Application Mode. This can be done using the Socket Mobile Companion app (recommended).

- Try our sample app [Capture MAUI SDK Sample](https://github.com/SocketMobile/capture_maui_sdk_sample) on Github.

## Windows

> **Note**
>
> The CaptureSDK for C# targets .NET 9 (MAUI), UWP and .NET Framework 4.8.

## Windows Requirements

- The **Socket Mobile Companion** software must be installed on the host PC. Download it from [GitHub](https://github.com/SocketMobile/companion-windows/releases).

## NuGet Package Installation

- Install the **SocketMobile.Capture** NuGet package through the NuGet Package Manager.

- The Newtonsoft JSON dependency will be installed automatically.

> **Note**
>
> The easiest way to use the CaptureSDK in your C# application is to use methods from the <b>CaptureHelper</b> class.

## Scanner Configuration

- By factory default, the scanner is configured in **Basic Mode** (keyboard emulation / HID).

- The scanner must be configured to **Application Mode** (Bluetooth Serial Port Profile / SPP) to work with CaptureSDK.

> **Warning**
>
> To setup <b>Application Mode</b>, open Companion app and follow instructions from the Setup page.
> <br>
> This configuration persists across power cycles until the scanner is reset to factory defaults.

## Pairing Process

- To clear existing pairings: power on the scanner, then hold the power and scan buttons simultaneously until shutdown (3 beeps confirm the reset).

- Pair the scanner via a Bluetooth address barcode or through the host Bluetooth settings.

- The Companion software must be running during the pairing process.

## Additional Requirements

- Your application will need a SocketMobile AppKey. Follow the link to [create an AppKey](/manage-apps). AppKeys can be generated online and at no additional cost beyond the nominal registration fee. The AppKey is validated by the CaptureSDK library on the device, no internet connection is required. Note: You don't need to create your own AppKey to compile and run the sample apps.

- Try our sample app [Capture MAUI SDK Sample](https://github.com/SocketMobile/capture_maui_sdk_sample) on Github.