Skip to main content

Managing User Sessions

The @blocklet/js-sdk provides a UserSessionService to help you fetch and manage user login sessions across different devices. This is particularly useful for building features like a "Security" or "Devices" page where users can see all their active sessions and understand where their account is being used.

This guide will walk you through the common use cases for managing user sessions.

Accessing the UserSessionService

First, get an instance of the Blocklet SDK. The UserSessionService is available under the userSession property.

SDK Initialization

javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

const sdk = getBlockletSDK();
const userSessionService = sdk.userSession;

Fetching Your Own Login Sessions

The most common task is to retrieve the list of sessions for the currently authenticated user. The getMyLoginSessions method allows you to do this with support for pagination and filtering.

Fetching the current user's sessions

javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

async function fetchMySessions() {
  try {
    const sdk = getBlockletSDK();
    // Fetch the first page of 10 online sessions
    const result = await sdk.userSession.getMyLoginSessions({}, {
      page: 1,
      pageSize: 10,
      status: 'online', // Optional filter: 'online' | 'expired' | 'offline'
    });

    console.log(`Total online sessions: ${result.paging.total}`);
    result.list.forEach(session => {
      console.log(`- Session on ${session.ua} last active at ${session.updatedAt}`);
    });
  } catch (error) {
    console.error('Failed to fetch sessions:', error);
  }
}

fetchMySessions();

Parameters

The method signature is getMyLoginSessions({ appUrl?: string }, params: UserSessionQuery). The second argument is a query object with the following parameters:

  • page number (default: 1) — The page number to retrieve.
  • pageSize number (default: 10) — The number of sessions per page.
  • status 'online' | 'expired' | 'offline' — Filter sessions by their current status.

Response

The method returns a promise that resolves to a UserSessionList object.

  • **** object — The response object containing the session list and pagination details.
    • list UserSession[] — An array of user session objects.
      • **** object — A single user session object.
        • id string — Unique identifier for the session.
        • appName string — Name of the application where the session was created.
        • appPid string — Blocklet PID of the application.
        • lastLoginIp string — The last known IP address for this session.
        • ua string — The User-Agent string of the client device.
        • updatedAt string — Timestamp of the last activity.
        • status string — The current status of the session (e.g., 'online').
        • userDid string — The DID of the user associated with the session.
    • paging object — Pagination information.
      • page number — The current page number.
      • pageSize number — The number of items per page.
      • total number — The total number of sessions matching the query.

Fetching Sessions for a Specific User

In some cases, like an admin dashboard, you might need to fetch login sessions for a user other than the one who is currently logged in. The getUserSessions method allows you to do this by providing a user's DID.

Fetching sessions for a specific DID

javascript
import { getBlockletSDK } from '@blocklet/js-sdk';

async function fetchUserSessions(userDid) {
  try {
    const sdk = getBlockletSDK();
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });

    console.log(`Found ${sessions.length} sessions for user ${userDid}:`);
    sessions.forEach(session => {
      console.log(`- Session ID: ${session.id}, App: ${session.appName}`);
    });
  } catch (error) {
    console.error(`Failed to fetch sessions for user ${userDid}:`, error);
  }
}

// Replace with the target user's DID
fetchUserSessions('zNK...some...user...did');

Parameters

  • did string (required) — The DID of the user whose sessions to fetch.
  • appUrl string — The base URL of the application. Defaults to the current Blocklet's service URL.

Response

The method returns a promise that resolves to an array of UserSession objects.

  • **** UserSession[] — An array of user session objects for the specified user.
    • **** object — A single user session object.
      • id string — Unique identifier for the session.
      • appName string — Name of the application where the session was created.
      • appPid string — Blocklet PID of the application.
      • ua string — The User-Agent string of the client device.
      • updatedAt string — Timestamp of the last activity.
      • status string — The current status of the session.
      • userDid string — The DID of the user associated with the session.

This guide has covered the primary ways to retrieve user session information using the SDK. For a complete list of all available methods and detailed type definitions, please refer to the UserSessionService API Reference.