管理用户会话

@blocklet/js-sdk 提供了一个 UserSessionService，帮助您在不同设备上获取和管理用户登录会话。这对于构建“安全”或“设备”页面等功能特别有用，用户可以在这些页面上查看所有活动会话，了解其帐户在何处被使用。

本指南将引导您了解管理用户会话的常见用例。

访问 UserSessionService

首先，获取 Blocklet SDK 的一个实例。UserSessionService 可在 userSession 属性下找到。

SDK Initialization

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

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

获取自己的登录会话

最常见的任务是检索当前已验证用户的会话列表。getMyLoginSessions 方法允许您执行此操作，并支持分页和筛选。

Fetching the current user's sessions

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();

参数

方法签名为 getMyLoginSessions({ appUrl?: string }, params: UserSessionQuery)。第二个参数是一个查询对象，包含以下参数：

page number (default: 1) — 要检索的页码。
pageSize number (default: 10) — 每页的会话数。
status 'online' | 'expired' | 'offline' — 根据当前状态筛选会话。

响应

该方法返回一个解析为 UserSessionList 对象的 Promise。

**** object — 包含会话列表和分页详细信息的响应对象。
- list UserSession[] — 用户会话对象数组。
  - **** object — 单个用户会话对象。
    - id string — 会话的唯一标识符。
    - appName string — 创建会话的应用程序名称。
    - appPid string — 应用程序的 Blocklet PID。
    - lastLoginIp string — 此会话的最后已知 IP 地址。
    - ua string — 客户端设备的用户代理字符串。
    - updatedAt string — 最后活动的时间戳。
    - status string — 会话的当前状态（例如，'online'）。
    - userDid string — 与会话关联的用户的 DID。
- paging object — 分页信息。
  - page number — 当前页码。
  - pageSize number — 每页的项目数。
  - total number — 与查询匹配的会话总数。

获取特定用户的会话

在某些情况下，例如管理员仪表板，您可能需要获取非当前登录用户的登录会话。getUserSessions 方法允许您通过提供用户的 DID 来实现此功能。

Fetching sessions for a specific DID

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');

参数

did string (required) — 要获取其会话的用户的 DID。
appUrl string — 应用程序的基础 URL。默认为当前 Blocklet 的服务 URL。

响应

该方法返回一个解析为 UserSession 对象数组的 Promise。

**** UserSession[] — 指定用户的用户会话对象数组。
- **** object — 单个用户会话对象。
  - id string — 会话的唯一标识符。
  - appName string — 创建会话的应用程序名称。
  - appPid string — 应用程序的 Blocklet PID。
  - ua string — 客户端设备的用户代理字符串。
  - updatedAt string — 最后活动的时间戳。
  - status string — 会话的当前状态。
  - userDid string — 与会话关联的用户的 DID。

本指南介绍了使用 SDK 检索用户会话信息的主要方法。有关所有可用方法和详细类型定义的完整列表，请参阅 UserSessionService API 参考。