UserSessionService

The UserSessionService provides an API for fetching and managing a user's login sessions across different devices and applications. This service is essential for building features that allow users to view their active login locations, see which devices have accessed their account, and manage those sessions.

For a practical guide on using this service, please refer to the Managing User Sessions guide.

Methods

getMyLoginSessions()

Retrieves a paginated list of the current user's own login sessions.

Parameters

options object — An object containing configuration options.
- appUrl string — The base URL of the application to query.
params UserSessionQuery (default: { page: 1, pageSize: 10 }) — An object for pagination and filtering.
- page number (required) — The page number to retrieve.
- pageSize number (required) — The number of items per page.
- status 'online' | 'expired' | 'offline' — Filter sessions by their status.

Returns

Promise Promise — A promise that resolves to an object containing a list of sessions and pagination details.

Example

Fetching My Online Sessions

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

const sdk = getBlockletSDK();

async function fetchMySessions() {
  try {
    const sessionData = await sdk.userSession.getMyLoginSessions(
      {},
      { page: 1, pageSize: 5, status: 'online' }
    );
    console.log('Online Sessions:', sessionData.list);
    console.log('Total online sessions:', sessionData.paging.total);
  } catch (error) {
    console.error('Failed to fetch sessions:', error);
  }
}

fetchMySessions();

Example Response

{
  "list": [
    {
      "id": "z8V...",
      "appName": "My Blocklet",
      "appPid": "my-blocklet-pid",
      "lastLoginIp": "192.168.1.1",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "updatedAt": "2023-10-27T10:00:00.000Z",
      "status": "online",
      "userDid": "zNK..."
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5,
    "total": 1
  }
}

getUserSessions()

Retrieves all login sessions for a specific user DID. This method is typically used in administrative contexts.

Parameters

options object (required) — An object containing the user's DID and optional app URL.
- did string (required) — The DID of the user whose sessions are to be fetched.
- appUrl string — The base URL of the application to query.

Returns

Promise<UserSession[]> Promise — A promise that resolves to an array of UserSession objects.

Example

Fetching Sessions for a Specific User

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

const sdk = getBlockletSDK();

async function fetchUserSessions(userDid) {
  try {
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });
    console.log(`Sessions for user ${userDid}:`, sessions);
  } catch (error) {
    console.error('Failed to fetch user sessions:', error);
  }
}

fetchUserSessions('zNK...userDid...'); // Replace with a valid user DID

Example Response

[
  {
    "id": "z8V...",
    "appName": "My Blocklet",
    "appPid": "my-blocklet-pid",
    "lastLoginIp": "192.168.1.1",
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "updatedAt": "2023-10-27T10:00:00.000Z",
    "status": "online",
    "userDid": "zNK..."
  }
]

loginByUserSession()

Initiates a new login based on an existing user session ID. This can be used for features like seamless sign-in across related applications.

Parameters

options object (required) — An object containing the session details required for login.
- id string (required) — The ID of the existing session to use for login.
- appPid string (required) — The PID of the application being logged into.
- userDid string (required) — The DID of the user associated with the session.
- passportId string (required) — The ID of the user's passport.
- appUrl string — The base URL of the application.

Returns

Promise<UserSession[]> Promise — A promise that resolves to an array containing the new user session.

Example

Logging In with an Existing Session

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

const sdk = getBlockletSDK();

async function loginWithSession(sessionDetails) {
  try {
    const newSessions = await sdk.userSession.loginByUserSession(sessionDetails);
    console.log('Successfully logged in with new session:', newSessions[0]);
  } catch (error) {
    console.error('Login by session failed:', error);
  }
}

const existingSession = {
  id: 'session_id_to_use',
  appPid: 'target_app_pid',
  userDid: 'zNK...userDid...',
  passportId: 'passport_id_string'
};

loginWithSession(existingSession);

Data Structures

The following are the primary data structures used by the UserSessionService.

UserSession

Represents a single login session for a user in a specific application.

id string (required) — Unique identifier for the session.
appName string (required) — The name of the application where the session originated.
appPid string (required) — The PID of the application.
lastLoginIp string (required) — The last known IP address for this session.
ua string (required) — The User-Agent string of the client device.
createdAt string — The timestamp when the session was created.
updatedAt string (required) — The timestamp of the last activity for this session.
status 'online' | 'expired' | 'offline' — The current status of the session.
user UserSessionUser — Detailed information about the user.
userDid string (required) — The DID of the user who owns the session.
visitorId string (required) — An identifier for the visitor/device.
passportId string | null (required) — The ID of the user's passport.
extra object (required) — Additional metadata.
- walletOS 'android' | 'ios' | 'web' (required) — The operating system of the wallet used.

UserSessionUser

Contains detailed information about the user associated with a session.

did string (required) — The user's Decentralized Identifier (DID).
fullName string (required) — The full name of the user.
email string (required) — The user's email address.
avatar string (required) — URL to the user's avatar image.
pk string (required) — The user's public key.
role string (required) — The user's role within the application (e.g., 'owner', 'admin').
roleTitle string (required) — The display title for the user's role.
sourceProvider 'wallet' | 'auth0' | 'nft' (required) — The provider used for authentication.
sourceAppPid string | null (required) — The PID of the application that sourced the user data.
remark string — Any remarks or notes about the user.

UserSessionList

A paginated list of user sessions.

list UserSession[] (required) — An array of user session objects.
paging object (required) — An object containing pagination details.
- page number (required) — The current page number.
- pageSize number (required) — The number of items per page.
- total number (required) — The total number of items.

UserSessionQuery

An object used to filter and paginate session queries.

page number (required) — The page number to retrieve.
pageSize number (required) — The number of sessions per page.
status 'online' | 'expired' | 'offline' — Filter sessions by their status.