> For the complete documentation index, see [llms.txt](https://docs.accurascan.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.accurascan.com/language/web-plugin/face-plugin/nextjs.md).

# Nextjs

## Accura Face Plugin — Next.js Integration Guide

This guide walks you through integrating the **Accura Face Plugin** into a Next.js project using the App Router.

***

### Prerequisites

Before proceeding, ensure the following requirement is met:

* **`accura.xml`** — Place your `accura.xml` file in the **`public/`** folder of your project as `public/accura.xml`. This file is required by the plugin to initialize the face detection engine. You can download it from here. 

{% file src="/files/AZ59uaCj1J7ouL8F2RM6" %}

### Step 1: Initialize Project

If you do not have an existing Next.js project, create one using the official CLI:

```bash
npx create-next-app@latest my-face-app
cd my-face-app
```

***

### Step 2: Install Plugin

Install the Accura Face Plugin package from the npm registry:

```bash
npm install accurafaceplugin
```

***

### Step 3: TypeScript Support

Since the `accurafaceplugin` package does not ship with TypeScript declarations, create a type definition file at the project root to resolve module errors and enable type checking:

```typescript
// types.d.ts (place in the project root)
declare module 'accurafaceplugin' {
  export default class FacePlugin {
    constructor(
      xmlPath: string,
      callback: (data: { base64: string }) => void,
      config: Record<string, string | number>
    );
    start(): Promise<void>;
    destroy(): void;
  }
}
```

Ensure this file is referenced in your `tsconfig.json`'s `include` array:

```json
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "types.d.ts"]
```

***

### Step 4: Implementation

Create `components/FaceScanner.tsx`. The snippet below demonstrates only the **plugin import and instantiation** — the minimal code required to activate the face detection engine in a Next.js client component:

```tsx
"use client"; // Required: marks this as a Client Component for browser-only execution

import { useEffect, useRef } from "react";
import type FacePlugin from "accurafaceplugin";

export default function FaceScanner() {
  const pluginRef = useRef<FacePlugin | null>(null); // Persists the plugin instance across renders
  const initialized = useRef<boolean>(false);         // Prevents double-init from React Strict Mode

  useEffect(() => {
    // Exit early if the plugin has already been initialized
    if (initialized.current) return;
    initialized.current = true;

    // Dynamically import the plugin at runtime to avoid SSR-related errors.
    // Next.js renders components on the server by default; browser APIs
    // (camera, DOM) are unavailable there. Dynamic import defers execution
    // to the client side only.
    import("accurafaceplugin").then((Module) => {
      const FacePlugin = Module.default;

      // Instantiate the plugin with the license path, capture callback, and UI configuration.
      pluginRef.current = new FacePlugin(
        "/accura.xml",   // Resolves to public/accura.xml at runtime
        base64Handler,   // Invoked automatically when a valid face is captured
        {
          threshold: 3,       // Detection strictness level (1–100)
          textSize: "",       // Overlay text size (uses default when empty)
          textColor: "",      // Overlay text color (uses default when empty)
          textWeight: "",     // Overlay text font weight (uses default when empty)
          textBgColor: "",    // Overlay text background (uses default when empty)
          BodyBgColor: "",    // Viewport background color (uses default when empty)
        }
      );

      // Launch the camera interface and begin the face detection session.
      pluginRef.current.start().then(() => {
        console.log("Accura Plugin Ready");
      });
    }).catch(err => {
      console.error("Failed to load FacePlugin:", err);
    });

    // Cleanup: invoked when the component unmounts (e.g., page navigation).
    // Ensures the camera stream is released and all plugin resources are freed.
    return () => {
      if (pluginRef.current) {
        pluginRef.current.destroy();
      }
    };
  }, []);

  return <></>;
}
```

***

### Step 5: Response Handling

Upon a successful face capture, the plugin invokes the `base64Handler` callback asynchronously. The callback receives a single argument — an object with a `base64` property containing the captured image encoded as a Base64 Data URL string (e.g., `data:image/jpeg;base64,/9j/...`).

**What is Base64?** Base64 is a binary-to-text encoding scheme that converts raw binary image data into a sequence of printable ASCII characters. The prefix segment (e.g., `data:image/jpeg;base64,`) conveys the MIME type, while the remainder is the encoded image payload. This format enables safe and seamless transmission of binary content over text-based protocols such as HTTP multipart form submissions.

The following handler demonstrates forwarding the captured image to a remote verification endpoint:

```tsx
// Invoked by the plugin upon each successful face capture event.
// Receives: { base64 } — a complete Data URL of the captured face image.
const base64Handler = async ({ base64 }: { base64: string }) => {
  console.log("Base64 received:", base64);

  try {
    // Compose a multipart form body to carry the base64-encoded image.
    const formData = new FormData();

    // Attach the image string under the field name expected by your backend.
    formData.append("imagebase64", base64);

    // Send the payload to your server-side face verification endpoint.
    // Replace with your actual backend host and path.
    const response = await fetch("https://ip:port/upload.php", {
      method: "POST",
      body: formData,
    });

    // Parse the JSON body of the server response.
    const data = await response.json();
    console.log("API Response:", data);

    // Inspect the liveness/match score returned by the verification service.
    if (data?.score !== undefined) {
      console.log(`Score: ${data.score}`);
    }
  } catch (error) {
    console.error("Error sending to API:", error);
  }
};
```

***

### Step 6: Demo Implementation

The following is the **complete, production-ready component**. Copy and paste it directly into `components/FaceScanner.tsx`. The original logic is preserved exactly as-is.

```tsx

"use client";

import { useEffect, useRef } from "react";
import type FacePlugin from "accurafaceplugin"; 

export default function FaceScanner() {
  const pluginRef = useRef<FacePlugin | null>(null);
  const initialized = useRef<boolean>(false);


  const base64Handler = async ({ base64 }: { base64: string }) => {
    console.log("Base64 received:", base64);

    try {
      const formData = new FormData();
      formData.append("imagebase64", base64);

      const response = await fetch("https://ip:port/upload.php", {
        method: "POST",
        body: formData,
      });

      const data = await response.json();
      console.log("API Response:", data);

      if (data?.score !== undefined) {
        console.log(`Score: ${data.score}`);
      }
    } catch (error) {
      console.error("Error sending to API:", error);
    }
  };

  useEffect(() => {
    if (initialized.current) return;
    initialized.current = true;

    import("accurafaceplugin").then((Module) => {
      const FacePlugin = Module.default;


      pluginRef.current = new FacePlugin(
        "/accura.xml",
        base64Handler,
        {
          threshold: 3,
          textSize: "",
          textColor: "",
          textWeight: "",
          textBgColor: "",
          BodyBgColor: "",
        }
      );


      pluginRef.current.start().then(() => {
        console.log("Accura Plugin Ready");
      });
    }).catch(err => {
      console.error("Failed to load FacePlugin:", err);
    });


    return () => {
      if (pluginRef.current) {
        pluginRef.current.destroy();
      }
    };
  }, []);

  return (
    <></>
  );
}
```

***

### Step 7: Usage

Import and render the component in your `app/page.tsx`:

```tsx
import FaceScanner from "./components/FaceScanner";

export default function Home() {
  return (
    <main>
      <FaceScanner />
    </main>
  );
}
```

***

### Step 8: Running the Project

```bash
npm run dev
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.accurascan.com/language/web-plugin/face-plugin/nextjs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.