# PixaProof Web SDK - Integration Guide
## Table of Contents
1. [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Installation](#installation)
2. [Examples](#examples)
- [Basic](#basic-example)
- [Advanced](#advanced-example)
3. [API Reference](#api-reference)
- [PixaProof Backend API](#pixaproof-backend-api)
- [SDK API](#sdk-api)
---
## Getting Started
### Requirements
| Dependency | Version | Notes |
|-----------|---------|-------|
| [pako](https://github.com/nodeca/pako) | ^2.x | Required for compression. **Must be loaded before the SDK.** |
| HTTPS | - | Camera and motion sensor APIs require a secure context. The SDK will not work over plain HTTP. |
### Installation
1. Download `pixaproof.umd.js` and host it alongside your page.
2. Load **pako** from CDN first, then load the SDK script.
```html
```
The SDK is then available globally as:
```js
const sdk = new PixaProof({
apiUrl: "{url}",
apiKey: "YOUR_API_KEY",
token: "YOUR_ACCESS_TOKEN_FROM_BACKEND",
elementId: "pixaproof-camera",
preferredCamera: "environment", // optional: "environment" (default), "user", or "any"
});
```
---
## Examples
### Basic Example
A minimal integration - only the required options and the most important callbacks.
> **Token note**: The `token` field expects an OAuth2 Bearer access token. **This token must be obtained from your own backend server** (which calls `/oauth2/token` with your `client_id` and `client_secret`) and then passed down to the frontend. Never call `/oauth2/token` directly from the browser, as doing so would expose your `client_secret`.
```html
PixaProof - Basic Example
Initializing...
```
---
### Advanced Example
Demonstrates all available options, all callbacks, UI customization, and non-critical permission banners.
```html
PixaProof - Advanced Example
Initializing...
```
---
## API Reference
### PixaProof Backend API
> **Security note**: All calls to the backend API that involve `client_id` or `client_secret` **must be made server-side**. Do not expose these credentials in browser code.
---
#### Get Client Access Token
Generates a short-lived OAuth2 Bearer token. Make this call from your **server**, then pass the resulting `access_token` to the frontend.
**Endpoint**
```
POST {url}/oauth2/token
Content-Type: application/x-www-form-urlencoded
```
**Request Parameters**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `client_id` | Yes | Your client ID |
| `client_secret` | Yes | Your client secret |
| `grant_type` | Yes | Must be `client_credentials` |
| `scope` | Yes | Must be `api.read api.write` |
**Example Response**
```json
{
"access_token": "eyJraWQiOiJ...",
"scope": "api.write api.read",
"token_type": "Bearer",
"expires_in": 899
}
```
Pass `access_token` to your frontend and supply it as the `token` option when constructing `PixaProof`.
---
#### Submit Image for Verification
Uploads a captured image (the `Blob` from `onCaptureSuccess`) to the backend for verification.
**Endpoint**
```
POST {url}/api/v1/verification/image
Authorization: Bearer
Content-Type: multipart/form-data
```
**Request Fields**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `apiKey` | Text | Yes | Your client API key |
| `image` | File | Yes | The image `Blob` returned by `onCaptureSuccess` |
| `referenceId` | Text | No | Optional identifier to correlate verification with your records |
**Example (browser fetch)**
```js
async function verifyImage(blob, accessToken) {
const formData = new FormData();
formData.append("apiKey", "YOUR_API_KEY");
formData.append("image", blob, "capture.png");
formData.append("referenceId", "user-session-123"); // optional
const response = await fetch("{url}/api/v1/verification/image", {
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});
return response.json();
}
```
##### Response Fields
| Field | Type | Values | Description |
|-------|------|--------|-------------|
| `overallResult` | string | `Pass` / `Fail` | Overall verification outcome |
| `verificationDetails.sourceOfOrigin` | string | `Mobile` / `Non-Mobile` / `null` | Whether the image was captured on a mobile device |
| `verificationDetails.integrityCheck` | string | `Pass` / `Fail` | Whether the integrity is intact and unmodified |
| `verificationDetails.livenessCapture` | string | `Pass` / `Fail` | Whether the image was captured live (not a replay or screenshot) |
| `geolocation` | object / `null` | - | Location at time of capture. `null` when `overallResult` is `Fail` |
| `geolocation.timezone` | string | - | IANA timezone name (e.g. `Asia/Kuala_Lumpur`) |
| `geolocation.datetime` | string | - | ISO 8601 capture timestamp |
| `geolocation.latitude` | string | - | Latitude coordinate |
| `geolocation.longitude` | string | - | Longitude coordinate |
##### Pass response
```json
{
"overallResult": "Pass",
"verificationDetails": {
"sourceOfOrigin": "Mobile",
"integrityCheck": "Pass",
"livenessCapture": "Pass"
},
"geolocation": {
"timezone": "Asia/Kuala_Lumpur",
"datetime": "2026-02-24T02:15:44.413Z",
"longitude": "101.586",
"latitude": "3.047"
}
}
```
##### Fail response
```json
{
"overallResult": "Fail",
"verificationDetails": {
"sourceOfOrigin": null,
"integrityCheck": "Fail",
"livenessCapture": "Fail"
},
"geolocation": null
}
```
---
### SDK API
#### Constructor
```js
const sdk = new PixaProof(options);
```
#### Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `apiUrl` | `string` | Yes | - | Base URL of your PixaProof backend |
| `apiKey` | `string` | Yes | - | Your client API key |
| `token` | `string` | Yes | - | OAuth2 Bearer access token (obtain server-side) |
| `elementId` | `string` | Yes | - | `id` of the DOM element the SDK renders into |
| `width` | `number` | No | `640` | Camera/canvas width in pixels |
| `height` | `number` | No | `480` | Camera/canvas height in pixels |
| `preferredCamera` | `"environment" \| "user" \| "any"` | No | `"environment"` | Preferred camera direction. The default prefers the rear camera and falls back if it cannot start. |
| `permissionUI` | `object` | No | - | Customise the permission prompt overlay (see below) |
| `cameraUI` | `object` | No | - | Customise the camera view elements (see below) |
| *(callbacks)* | `function` | No | - | See [Callbacks](#callbacks) below |
---
#### `permissionUI` Options
Each sub-key accepts a `styles` object (CSS property → value) and/or a `className` string.
| Sub-key | Description |
|---------|-------------|
| `overlay` | Full-screen backdrop behind the permission card |
| `container` | The card/box containing the message and button |
| `message` | Text area inside the card. Also accepts `html` (string) for rich content |
| `button` | The "Enable Permissions" button. Also accepts `text` and `loadingText` strings |
Pass `styles: {}` to strip all built-in default styles from an element.
---
#### `cameraUI` Options
Each sub-key accepts `styles` and/or `className`.
| Sub-key | Description |
|---------|-------------|
| `wrapper` | Outer wrapper around the camera card |
| `card` | Card element that holds the video |
| `videoWrapper` | Wrapper directly around the `