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

# Get Started

> Learn how to get started integrating the Liveness SDK into your app with step-by-step instructions for Web Browser, Android, and iOS platforms.

### Required Parameters

When integrating the Liveness SDK, you will need to provide the following parameters:

* **serviceBaseUrl**\
  The endpoint where the liveness service is hosted.\
    • For **Demo** environments, use: `https://d1.cynopsis.co/service`\
    • For **Production** environments, use: `https://util.cynopsis.co/service`

* **accessToken**\
  The authentication token required to access the SDK services.\
  Obtain your access token by referring to the **Authentication** section above.

* **domainId**\
  Your unique domain identifier, provided by Cynopsis Solutions or your system administrator.

* **provider**\
  The liveness provider version. Currently, set this to: `V2`

These parameters must be passed into the SDK initialization as shown in the integration examples below.

### Intergrate SDK

To start integrating the SDK with your application codebase, follow the sample code provided for your platform below. Each example shows how to initialize and configure the SDK using the required parameters, helping you get up and running quickly.

<Tabs>
  <Tab title="Web Browser">
    ### Web Browser Integration

    1. [Download Web SDK](/sdk/react-cs-liveness-3.4.44.tgz)

    2. **Install the SDK** in your React project:

    > **Note:** The Web SDK requires `react` and `react-dom` (version `>=16.8.0`), as well as `react-cs-liveness`.

    ```bash theme={null}
    npm install react@^16.8.0 react-dom@^16.8.0
    npm install ./react-cs-liveness-3.4.44.tgz
    # or
    yarn add react@^16.8.0 react-dom@^16.8.0
    yarn add ./react-cs-liveness-3.4.44.tgz
    ```

    3. **Integrate the Liveness component**

    Select your frontend framework below for sample code:

    <Tabs groupId="liveness-web-framework">
      <Tab title="Vanilla JS (CommonJS)">
        ```html theme={null}
        <!-- Vanilla JS Example -->
        <script src="path/to/react-cs-liveness/vanilla.js"></script>
        <script>
          // Vanilla JS
          const detector = document.createElement('liveness-detector');
          detector.setAttribute('service-base-url', 'YOUR_SERVICE_BASE_URL');
          detector.setAttribute('domain-id', 'YOUR_DOMAIN_ID');
          detector.setAttribute('access-token', 'YOUR_ACCESS_TOKEN');
          detector.setAttribute('provider', 'V2');
          detector.addEventListener('liveness-ready', () => detector.start());
          detector.addEventListener('liveness-result', (e) => {
            // handle result
            console.log(e.detail);
          });
          document.body.appendChild(detector);
        </script>
        ```
      </Tab>

      <Tab title="React">
        ```jsx theme={null}
        import { LivenessCheck } from 'react-cs-liveness';

        function App() {
          return (
            <LivenessCheck
              serviceBaseUrl="YOUR_SERVICE_BASE_URL"
              accessToken="YOUR_ACCESS_TOKEN"
              domainId="YOUR_DOMAIN_ID"
              provider="V2"
              onReady={() => {
                // handle ready
              }}
              onResult={result => {
                // handle result
              }}
            />
          );
        }
        ```
      </Tab>

      <Tab title="Vue">
        ```vue theme={null}
        <template>
          <!-- Vue Example -->
          <liveness-detector
            :service-base-url="apiUrl"
            :domain-id="domainId"
            :access-token="accessToken"
            provider="V2"
            @liveness-ready="onReady"
            @liveness-result="onResult"
          ></liveness-detector>
        </template>

        <script>
        export default {
          data() {
            return {
              apiUrl: "YOUR_SERVICE_BASE_URL",
              domainId: "YOUR_DOMAIN_ID",
              accessToken: "YOUR_ACCESS_TOKEN"
            }
          },
          methods: {
            onReady() {
              // handle ready
            },
            onResult(e) {
              // handle result
              console.log(e);
            }
          }
        }
        </script>
        ```
      </Tab>

      <Tab title="Angular">
        > **Update your `angular.json` to include the following style configuration:**
        >
        > ```json theme={null}
        > {
        >   "projects": {
        >     "angular-cli-cs-liveness-demo": {
        >       "architect": {
        >         "build": {
        >           "options": {
        >             "styles": [
        >               "node_modules/@aws-amplify/ui-react/styles.css",
        >               "src/styles.css"
        >             ]
        >           }
        >         }
        >       }
        >     }
        >   }
        > }
        > ```
        >
        > Ensure that `"node_modules/@aws-amplify/ui-react/styles.css"` appears **before** your custom styles in the `styles` array under the appropriate project's build options.

        ```html theme={null}
        <!-- Angular Example -->
        <liveness-detector
          [serviceBaseUrl]="apiUrl"
          [domainId]="domainId"
          [accessToken]="accessToken"
          provider="V2"
          (liveness-ready)="onReady()"
          (liveness-result)="onResult($event)">
        </liveness-detector>
        ```

        ```typescript theme={null}
        // In your Angular component
        apiUrl = "YOUR_SERVICE_BASE_URL";
        domainId = "YOUR_DOMAIN_ID";
        accessToken = "YOUR_ACCESS_TOKEN";

        onReady() {
          // handle ready
        }

        onResult(result: any) {
          // handle result
          console.log(result);
        }
        ```
      </Tab>
    </Tabs>

    #### About Code Splitting & Custom Chunking

    If your project uses custom code-splitting or defines manual chunks (such as in a Vite or Webpack config), make sure all `react-cs-liveness` dependencies are kept together in the same chunk. Incorrect configuration may cause runtime issues related to duplicate React instances or missing dependencies, especially when using React 18+ or advanced bundling.

    * We recommend not setting custom chunking rules for the SDK or to use our provided plugins (see below) to ensure correct bundling.
    * If you are not sure about your chunking setup, test your build to ensure the Liveness component loads and works as expected.

    <Accordion title="Click here for Vite setup instructions">
      If your project uses [Vite](https://vitejs.dev/), we strongly recommend using our official `liveness()` Vite plugin from `react-cs-liveness/config`.
      This plugin ensures correct code-splitting and chunking for all `react-cs-liveness` dependencies, avoiding runtime errors (like React 18+ createRoot issues) that commonly occur when custom `manualChunks` are defined.

      For example, with a Vue project:

      ```js theme={null}
      // vite.config.js
      import { defineConfig } from 'vite'
      import { liveness } from 'react-cs-liveness/config'

      export default defineConfig({
        plugins: [
          liveness({
            mergeWithExisting: true, // Merge safely with your existing manualChunks
          }),
        ],
      })
      ```

      This setup ensures `react-cs-liveness` and all its internal dependencies are correctly bundled—no matter your framework or chunking rules. The `mergeWithExisting: true` option integrates seamlessly with your app’s existing Vite code-splitting configuration.
    </Accordion>
  </Tab>

  <Tab title="Android">
    ### Android Integration

    1. **Download the SDK:**

       [Download Android SDK](/sdk/liveness-release.aar)

    2. **Add dependencies to your app-level `build.gradle`:**

    > **Tested with Gradle 8.13.0:**\
    > The following configuration has been verified with [Gradle 8.13.0](https://docs.gradle.org/8.13.0/release-notes.html).

    ```groovy theme={null}
    // Enable core library desugaring in your build.gradle
    android {
        compileOptions {
            coreLibraryDesugaringEnabled true
            // other compile options if any
        }
    }

    dependencies {
        implementation project(path: ':liveness-release')
        implementation 'com.amplifyframework:core:2.30.1'
        implementation 'com.amplifyframework.ui:liveness:1.7.1'
        implementation 'androidx.compose.material3:material3:1.4.0'
        implementation 'androidx.compose.material:material-icons-extended:1.7.8'
        implementation 'com.amplifyframework:aws-auth-cognito:2.30.1'
        coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
    }
    ```

    3. **Implementing the Liveness SDK in Your Activity**

    Here's a simple and practical example to get you quickly started with the Liveness SDK in your Android app:

    ```java theme={null}
    // 1. Create LivenessTestConfig with your access token and service URL
    LivenessTestConfig config = new LivenessTestConfig(
        Provider.V2,
        "https://d1.cynopsis.co/service",
        1L, // your domain ID
        "YOUR_ACCESS_TOKEN"
    );

    // 2. Setup LivenessOnLoad callback to handle SDK ready or failure state
    LivenessOnLoad livenessOnLoad = new LivenessOnLoad() {
        @Override
        public void succeed(String message) {
            // SDK initialized successfully
            setLivenessCustomization();
        }

        @Override
        public void failed(String message) {
            // SDK initialization failed
        }
    };

    // Initialize the LivenessTest
    LivenessTest liveness = new LivenessTest(this, config, livenessOnLoad);

    // 3. Start liveness detection with custom delegate to receive results
    LivenessTestDelegate livenessTestDelegate = new LivenessTestDelegate() {
        @Override
        public void onResponse(LivenessTestResults response) {
            switch (response.getStatus()) {
                case PASSED:
                    // Success: handle result
                    break;
                case ERROR:
                case FAILED:
                    // Handle error or failed attempt
                    break;
            }
        }
    };
    liveness.startLiveness(livenessTestDelegate);

    // 4. Customization color (optional)
    private void setLivenessCustomization() {
        LivenessV2Customization customization = new LivenessV2Customization().getDefault();

        customization.setBackground(0xFFf2e8cf);
        customization.setPrimary(0xffbc4749);
        customization.setOnPrimary(0xFFf2e8cf);
        customization.setOnBackground(0xffbc4749);

        LivenessTestV2GlobalState.setCustomization(customization);
    }
    ```

    > **Tip:** Replace `"YOUR_ACCESS_TOKEN"` with your real access token provided via onboarding, and make sure IDs like `startButton`, `messageResult`, `messageStatus`, and `imageResult` exist in your `activity_main.xml`.

    This example will initialize the SDK, show status and liveness selfie results, and display passed/failed messages for your users.
  </Tab>

  <Tab title="iOS">
    ### iOS Integration

    1. **Download the SDK:**

       [Download iOS SDK](/sdk/Liveness.xcframework.zip)

    2. **Add the SDK framework to your Xcode project:**

       * Unzip `Liveness.xcframework.zip` and drag the `Liveness.xcframework` folder into the `Frameworks` group of your Xcode project.

    3. **Add the Amplify UI Swift Liveness package:**

       * In Xcode, go to **File > Add Packages...**
       * Paste the following URL into the search bar:\
         `https://github.com/Cynopsis/amplify-ui-swift-liveness`
       * Click **Add Package** when it appears.

    4. **Embed Liveness.xcframework:**
       * In your Xcode project settings, go to **General > Frameworks, Libraries, and Embedded Content**.
       * Make sure **Liveness.xcframework** is listed, and its embed option is set to **Embed & Sign**.

    5. **Import and use the framework in your code:**

    ```swift theme={null}
    import Liveness

    class ViewController: UIViewController {

        // 1. Prepare session credentials and configuration
        let credentials = LivenessCredentials(
            serviceBaseUrl: "YOUR_SERVICE_BASE_URL",      // e.g. "https://util.cynopsis.co/service"
            accessToken: "YOUR_ACCESS_TOKEN",             // OAuth token from onboarding
            domainId: "YOUR_DOMAIN_ID",                   // Provided by Cynopsis
            provider: "V2"                                // Use "V2"
        )

        // 2. (Optional) Set up color customization
        func customColorConfig() -> LivenessColorConfiguration {
            let config = LivenessColorConfiguration()
            config.background = 0xFFf2e8cf
            config.primary = 0xffbc4749
            config.onPrimary = 0xFFf2e8cf
            config.onBackground = 0xffbc4749
            return config
        }

        // 3. Start liveness detection and handle results
        func startLivenessCheck() {
            _ = LivenessTestV2Processor(
                fromVC: self,
                config: credentials,
                complete: { result in
                    switch result.status {
                    case .PASSED:
                        // Success: handle result
                        print("Liveness passed: \(result)")
                    case .FAILED, .ERROR:
                        // Handle failed attempt or error
                        print("Liveness failed: \(result.message ?? "Unknown error")")
                    default:
                        break
                    }
                },
                customization: customColorConfig()
            )
        }
    }
    ```

    > **Tip:** Replace `"YOUR_ACCESS_TOKEN"` and other credentials with your actual values. Make sure your ViewController is presented correctly in your app flow.

    This example initializes the SDK, applies optional color customization, and shows how to handle pass/fail messages for user feedback.
  </Tab>
</Tabs>