Installation

This guide covers installing the Averer Web SDK into an existing React project and rendering the SDK for the first time.

Prerequisites

• Node.js v18 or later
• A React 18+ project (Next.js App Router, Vite, or similar)
• A configId from Averer support

Install the SDK

npm install @averer/averer-websdk

Initialise the SDK

Wrap your application (or the relevant subtree) with AvererSdkProvider and render the AvererWebSdk component where you want the verification flow to appear.

The snippet below demonstrates how to render the SDK inside a Next.js App Router page. Adjust imports and component placement for your application.

'use client';

import {
  AvererWebSdk,
  AvererSdkProvider,
  type SdkQuery,
  type SdkSuccessRes,
} from '@averer/averer-websdk';

export default function EligibilityPage() {
  const sdkQuery: SdkQuery = [
    {
      id: 5,
      circuitId: 'credentialAtomicQuerySigV2',
      subjectTitle: 'Pass AML & CTF Checks',
      query: {
        allowedIssuers: [
          'did:receptor:redbelly:testnet:31K3oHpCV428AkXUYTL89q6LCvHcSqHirdv7z6LHtu9',
        ],
        type: 'AMLCTFCredential',
        context:
          'https://raw.githubusercontent.com/redbellynetwork/receptor-schema/refs/heads/main/schemas/json-ld/AMLCTFCredential.jsonld',
        credentialSubject: {
          amlCheckStatus: { $eq: 'passed' },
        },
      },
    },
  ];

  const handleSuccess = (data: SdkSuccessRes) => {
    if (data.eligibility.passed) {
      console.log('Verification successful', data);
    }
  };

  const handleError = (reason: string) => {
    console.error('Verification failed:', reason);
  };

  return (
    <AvererSdkProvider configId="your-config-id">
      <AvererWebSdk
        appName="My App"
        sdkQuery={sdkQuery}
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </AvererSdkProvider>
  );
}

Note: To obtain a configId, please contact Averer support.

Testing note: In non-production Dynamic environments, the SDK disables the social-linking gate by default so test users can create multiple accounts more easily. If you need to exercise that screen during QA, pass settings={{ testing: { socialLinkingRequired: true } }} to AvererWebSdk.

Handling initialization errors

If the SDK can't fetch its config (bad configId, network failure, etc.), it renders a built-in red error message by default. You can override this with your own UI and wire telemetry via the errorFallback and onError props:

<AvererSdkProvider
  configId="your-config-id"
  loadingFallback={<Spinner />}
  errorFallback={(error, retry) => (
    <div>
      <p>Couldn't start the SDK ({error.code}). {error.message}</p>
      <button onClick={retry}>Try again</button>
    </div>
  )}
  onError={(error) => Sentry.captureException(error)}
>
  {/* ... */}
</AvererSdkProvider>

The error argument is a typed SdkConfigError whose code lets you branch UX (e.g. only offer "Try again" for 'network'). See the API Reference for the full prop list and error codes.

What happens next

Once the SDK is initialised, users will be guided through:

1. Authentication: log in via email or social accounts
2. Identity verification: complete KYC/KYB through the SDK's built-in flow
3. Credential issuance: receive verifiable credentials in their embedded wallet
4. Proof generation: generate and submit zero-knowledge proofs against your configured queries

To learn more about the embedded wallet that powers this flow, see Averer Wallet. To configure verification queries, see Verify with Averer.