mirror of
https://github.com/selfxyz/self.git
synced 2026-02-19 02:24:25 -05:00
202 lines
9.3 KiB
Markdown
202 lines
9.3 KiB
Markdown
# @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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```ts
|
||
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:
|
||
|
||
```ts
|
||
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`](#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:
|
||
|
||
```ts
|
||
import { getUniversalLink } from '@selfxyz/qrcode-angular';
|
||
|
||
const link = getUniversalLink({
|
||
...selfApp,
|
||
deeplinkCallback: 'https://your-app.com/callback',
|
||
});
|
||
```
|
||
|
||
```html
|
||
<a [href]="link" target="_blank">Open Self App</a>
|
||
```
|
||
|
||
---
|