self/sdk/qrcode-angular

@selfxyz/qrcode-angular

@selfxyz/qrcode-angular is an Angular library for generating verification QR codes that link to the Self.xyz app. It allows developers to define what user data (disclosures) should be requested during verification (such as nationality, age checks, or OFAC restrictions) and automatically builds a QR code that users can scan with the Self app to complete verification.

With a few lines of code, you can:

• Configure disclosures like minimum age, excluded countries, OFAC checks, or DG1 passport fields.
• Generate a SelfApp configuration via SelfAppBuilder.
• Render a QR code that works out-of-the-box with WebSocket or deep link flows.
• Handle success and error callbacks when verification is completed.

This library is the Angular equivalent of the Self QR code React SDK, making it easy to embed Self-powered verification flows into Angular applications.

@selfxyz/angular-qrcode

SelfQRcodeComponent is an Angular standalone component for rendering QR codes that connect users to Self.xyz's flows. It manages session creation, WebSocket connections, and real-time proof state updates, while providing visual feedback through LED states.

---

✨ Features

• Generates a unique session ID for every instance.
• Displays a QR code for Self app deep linking or WebSocket flow.
• Handles WebSocket lifecycle (connection, cleanup, proof step updates).
• Emits success and error callbacks when verification completes.
• Supports light/dark mode and configurable QR size.
• Includes success/error animations with ngx-lottie.

---

📦 Installation

npm install @selfxyz/qrcode-angular

Also ensure you have Angular v15+ with standalone components enabled.

---

🔧 Setup

You'll need to add the provider to your application's bootstrap configuration:

import { bootstrapApplication } from '@angular/platform-browser';
import { appConfig } from './app/app.config';
import { App } from './app/app';
import { provideSelfLottie } from '@selfxyz/qrcode-angular';

bootstrapApplication(App, {
  ...appConfig,
  providers: [...appConfig.providers, provideSelfLottie()],
}).catch((err) => console.error(err));

This provider is required for the Lottie animations used in success/error states.

---

⚡ Usage

Import the Component

Since it’s standalone, you can import it directly into any feature component:

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { SelfQRcodeComponent, type SelfApp } from '@selfxyz/qrcode-angular';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [CommonModule, SelfQRcodeComponent],
  template: `
    <lib-self-qrcode
      [selfApp]="selfApp"
      [successFn]="onSuccess"
      [errorFn]="onError"
      [darkMode]="false"
      [size]="300"
    >
    </lib-self-qrcode>
  `,
})
export class DemoComponent {
  selfApp: SelfApp = {
    appName: 'Demo App',
    scope: 'demo-scope',
    endpoint: 'https://your-api.com/verify',
    endpointType: 'https',
    logoBase64: 'https://i.imgur.com/Rz8B3s7.png',
    userId: '0x123...', // a uuid or address
    disclosures: {
      nationality: true,
      minimumAge: 18,
      ofac: true,
    },
    version: 2,
  };

  onSuccess() {
    console.log('✅ Verification successful!');
  }

  onError(err: { error_code?: string; reason?: string }) {
    console.error('❌ Verification failed', err);
  }
}

---

🔧 Component API

Inputs

Input	Type	Default	Description
selfApp	SelfApp (required)	—	The configured Self app instance.
successFn	() => void (required)	—	Callback triggered when verification succeeds.
errorFn	(data: { error_code?: string; reason?: string }) => void	—	Callback triggered when verification fails.
type	'websocket' | 'deeplink'	'websocket'	Determines whether to use WebSocket or deep link QR.
websocketUrl	string	WS_DB_RELAYER	Custom WebSocket relay URL.
size	number	300	Size of the QR code in pixels.
darkMode	boolean	false	Toggles light/dark mode for QR code styling.

---

SelfApp

Property	Type	Required	Description
appName	string	✅	The display name of your app shown in the Self flow.
logoBase64	string (URL or Base64-encoded image)	✅	The app’s logo (shown to the user during verification).
endpointType	EndpointType	✅	staging_https | https | celo | staging_celo
endpoint	string	✅	API endpoint where proof is verified (endpoint url or a contract address)
deeplinkCallback	string	Optional	Callback URL for deep link flows.
scope	string	✅	Unique identifier for your application
userId	string	✅	Unique identifier for the end user (address or a uuid)
userIdType	UserIdType	Optional	Type of identifier used (email, phone, etc.).
disclosures	SelfAppDisclosureConfig	✅	Defines which fields are requested during verification.
version	number	✅	Schema version (e.g., 2).
userDefinedData	string	Optional	Arbitrary developer-defined metadata.

---

SelfAppDisclosureConfig

Property	Type	Default	Description
issuing_state	boolean	false	Request the issuing state from the document.
name	boolean	false	Request the full name from the document
passport_number	boolean	false	Request the document number.
nationality	boolean	false	Request the user’s nationality.
date_of_birth	boolean	false	Request the date of birth.
gender	boolean	false	Request the gender field.
expiry_date	boolean	false	Request the passport expiry date.
ofac**	boolean	false	Check against OFAC sanction lists.
excludedCountries**	Country3LetterCode[]	[]	Exclude users from specific ISO 3166-1 alpha-3 countries.
minimumAge**	number	—	Require a minimum age (e.g., 18 (upto 99)).

** ⚠️ Important: These fields must match your backend configuration.

---

🎬 Lifecycle

• On init:

  • Generates a UUID session ID.
  • Establishes a WebSocket connection.
  • Sets the QR code value.

• On destroy:

  • Cleans up the WebSocket connection.

---

Mobile usage

It's scan to use QR codes on mobile. Instead you'll you want to use the deeplink flow instead of WebSocket, and you’ll need to import the getUniversalLink helper from the library. Pass your configured selfApp object into it along with a deeplinkCallback URL. The generated link can then be attached to a button or anchor tag, which will open the Self app directly.

Example:

import { getUniversalLink } from '@selfxyz/qrcode-angular';

const link = getUniversalLink({
  ...selfApp,
  deeplinkCallback: 'https://your-app.com/callback',
});

<a [href]="link" target="_blank">Open Self App</a>

---