Skip to content

Web SDK Quick Start

This page provides a minimal conceptual example of embedding a Polyguard trust check in a web application. For the complete SDK reference -- including all configuration options, event types, error handling, and advanced usage -- see the full documentation at dev.polyguard.ai.

Overview

The Web SDK handles the end-user-facing portion of a trust check in the browser: displaying the verification modal, coordinating the WebSocket session with the Polyguard mobile app, and returning results to your application via callbacks.

The typical integration flow is:

  1. Server-side: Create a Link via the REST API (the Preparation phase).
  2. Client-side: Initialize the Web SDK, start the trust check with the Link URL, and handle results.
  3. Server-side (optional): Receive results via webhook for backend validation.

Before displaying a trust check to an End User, your backend creates a Link via the Polyguard REST API. This requires a valid session token.

import requests

response = requests.post(
    "https://api-global.polyguard.ai/api/v1/links",
    headers={"Authorization": f"Bearer {session_token}"},
    json={
        "title": "Identity Verification",
        "required_proofs": ["government_id", "pg_presence"],
    },
)

link_data = response.json()
link_url = link_data["url"]  # Pass this to the frontend

Reusable Links

Links are reusable by default. If your workflow requires a fresh Link per transaction, create a new one each time. If verification requirements are stable, you can create a Link once and reuse it across sessions.

Step 2: Initialize the SDK (Client-Side)

Include the Polyguard Web SDK in your page and initialize it with your App ID.

<script src="https://cdn.polyguard.ai/sdk/latest/polyguard.js"></script>

// Initialize the SDK with your App ID
const polyguard = new Polyguard({
  appId: "your-app-id",
  environment: "production",  // or "sandbox" for testing
});

Step 3: Start a Trust Check

Trigger a trust check by passing the Link URL obtained from your backend. The SDK opens a modal overlay where the End User completes their verification using the Polyguard mobile app.

polyguard.startTrustCheck({
  linkUrl: linkUrl,  // From Step 1

  onComplete: (result) => {
    // Trust check completed successfully
    console.log("Verification status:", result.status);
    console.log("Session ID:", result.sessionId);
    console.log("Proofs presented:", result.proofs);

    // Update your UI -- e.g., unlock the next step
    showVerifiedState(result);
  },

  onError: (error) => {
    // Trust check failed or was cancelled
    console.error("Trust check error:", error.code, error.message);

    // Handle gracefully -- e.g., offer retry
    showErrorState(error);
  },

  onStatusChange: (status) => {
    // Optional: track progress through the trust check
    // e.g., "waiting_for_mobile", "verifying", "processing"
    updateProgressIndicator(status);
  },
});

Step 4: Handle Results (Server-Side, Optional)

If your App is configured with a webhook URL, Polyguard will POST trust check results to your backend as well. This is useful for server-side validation and record-keeping, independent of what happens in the browser.

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/polyguard", methods=["POST"])
def handle_polyguard_webhook():
    payload = request.json

    session_id = payload["session_id"]
    status = payload["status"]
    proofs = payload["proofs"]

    # Validate and store the result server-side
    record_verification(session_id, status, proofs)

    return "", 200

Always validate server-side

While the SDK callback provides immediate results for UI updates, treat the webhook (or a subsequent API call to retrieve session results) as the authoritative source for your backend logic. Client-side callbacks can be intercepted or replayed.

Sandbox vs. Production

The Web SDK supports a sandbox environment for development and testing. Sandbox trust checks simulate the verification flow without requiring real identity documents or a physical mobile device.

Environment Endpoint Purpose
sandbox Sandbox API Development, testing, demos
production api-global.polyguard.ai Live trust checks with real verification

Switch environments by changing the environment parameter during SDK initialization.

What's Next