Used to check for browser translation.
用于检测浏览器翻译。
ブラウザの翻訳を検出する
Advanced Topics

Event Handling

The WalletHandlers instance is an EventEmitter, allowing you to listen for key moments in the DID Connect authentication lifecycle. This enables you to build responsive applications that can update the UI in real-time or log session activity without relying on constant polling. By subscribing to these events, you gain deeper insight into the authentication flow and can trigger actions based on its state.

Authentication Lifecycle Events#

The following diagram illustrates when each major event is emitted during a typical DID Connect session:

DID WalletDID Connect ServiceWeb ApplicationDID WalletDID Connect ServiceWeb ApplicationDisplay QR CodeUser reviews and approves requestSession is complete, cleanup timer startsRequest new session (e.g., GET /token)Returns new tokenemit('created', {token, ...})Scan QR, fetch auth data (e.g., GET /auth?_t_=...)emit('scanned', sessionData)Return auth challengeSubmit signed response (e.g., POST /auth)Verify response, process claimsemit('succeed', sessionData)emit('deleted', {token})

Available Events#

The WalletHandlers class emits several events you can subscribe to. The underlying BaseHandler listens to the token storage and emits foundational events, while WalletHandlers provides higher-level events for key user actions.

Event Name

Payload Data

Description

created

object

Emitted when a new session is created and a token is generated. The payload contains the initial session data.

updated

object

Emitted whenever session data is updated. This is a general-purpose event for state changes.

scanned

object

A specific updated event, emitted when the user scans the QR code with their DID Wallet.

succeed

object

Emitted after the user approves the request in their wallet and the server successfully verifies the response.

deleted

{ token: string }

Emitted when a session token is destroyed, either after a successful completion or upon expiration.

error

Error

Emitted when an error occurs at any point during the authentication flow.

Monitor a Session#

You can attach listeners directly to the WalletHandlers instance to monitor the progress of an authentication request. This is useful for providing real-time feedback to the user or for server-side logging.

Here is how you can set up listeners for the core events:

const WalletHandlers = require('@did-connect/handler');
// Assume authenticator and tokenStorage are already configured

const handlers = new WalletHandlers({
authenticator,
tokenStorage,
});

// 1. Listen for when a new session is created
handlers.on('created', (session) => {
console.log(`[Event: created] New session started with token: ${session.token}`);
});

// 2. Listen for when the QR code is scanned
handlers.on('scanned', (session) => {
console.log(`[Event: scanned] Wallet connected for token: ${session.token}`);
// You can use this event to push a UI update to the client
});

// 3. Listen for a successful authentication
handlers.on('succeed', (session) => {
console.log(`[Event: succeed] User ${session.userDid} authenticated successfully.`);
});

// 4. Listen for when a session is cleaned up
handlers.on('deleted', ({ token }) => {
console.log(`[Event: deleted] Session token ${token} was removed.`);
});

// 5. Listen for any errors during the process
handlers.on('error', (error) => {
console.error('[Event: error] An error occurred:', error.message);
});

// Attach handlers to your Express app
// ...

This setup provides a complete, real-time log of the authentication journey for each user, directly on your server.


Now that you understand how to monitor the authentication lifecycle, you may want to learn how to request specific data from the user by exploring Claims.

previous
Customizing URLs