UserSessionService

UserSessionService 提供了一个 API，用于获取和管理用户在不同设备和应用程序中的登录会话。该服务对于构建功能至关重要，这些功能允许用户查看其活跃的登录位置、了解哪些设备访问了他们的账户以及管理这些会话。

有关使用此服务的实用指南，请参阅管理用户会话指南。

方法

getMyLoginSessions()

检索当前用户自己的登录会话的分页列表。

参数

options object — 一个包含配置选项的对象。
- appUrl string — 要查询的应用程序的基础 URL。
params UserSessionQuery (default: { page: 1, pageSize: 10 }) — 一个用于分页和筛选的对象。
- page number (required) — 要检索的页码。
- pageSize number (required) — 每页的项目数。
- status 'online' | 'expired' | 'offline' — 按会话状态筛选。

Promise Promise — 一个解析为包含会话列表和分页详细信息的对象的 Promise。

示例

获取我的在线会话

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('在线会话：', sessionData.list);
    console.log('在线会话总数：', sessionData.paging.total);
  } catch (error) {
    console.error('获取会话失败：', error);
  }
}

fetchMySessions();

响应示例

{
  "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()

检索特定用户 DID 的所有登录会话。此方法通常用于管理场景。

参数

options object (required) — 一个包含用户 DID 和可选应用 URL 的对象。
- did string (required) — 要获取其会话的用户的 DID。
- appUrl string — 要查询的应用程序的基础 URL。

Promise<UserSession[]> Promise — 一个解析为 UserSession 对象数组的 Promise。

示例

获取特定用户的会话

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

const sdk = getBlockletSDK();

async function fetchUserSessions(userDid) {
  try {
    const sessions = await sdk.userSession.getUserSessions({ did: userDid });
    console.log(`用户 ${userDid} 的会话：`, sessions);
  } catch (error) {
    console.error('获取用户会话失败：', error);
  }
}

fetchUserSessions('zNK...userDid...'); // 替换为有效的用户 DID

响应示例

[
  {
    "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()

基于现有用户会话 ID 发起新登录。此功能可用于实现跨相关应用程序的无缝登录等功能。

参数

options object (required) — 一个包含登录所需会话详细信息的对象。
- id string (required) — 用于登录的现有会话的 ID。
- appPid string (required) — 要登录的应用程序的 PID。
- userDid string (required) — 与会话关联的用户的 DID。
- passportId string (required) — 用户 Passport 的 ID。
- appUrl string — 应用程序的基础 URL。

Promise<UserSession[]> Promise — 一个解析为包含新用户会话的数组的 Promise。

示例

使用现有会话登录

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

const sdk = getBlockletSDK();

async function loginWithSession(sessionDetails) {
  try {
    const newSessions = await sdk.userSession.loginByUserSession(sessionDetails);
    console.log('使用新会话成功登录：', newSessions[0]);
  } catch (error) {
    console.error('通过会话登录失败：', error);
  }
}

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

loginWithSession(existingSession);

数据结构

UserSessionService 使用的主要数据结构如下。

UserSession

表示用户在特定应用程序中的单个登录会话。

id string (required) — 会话的唯一标识符。
appName string (required) — 会话来源的应用程序名称。
appPid string (required) — 应用程序的 PID。
lastLoginIp string (required) — 此会话的最后已知 IP 地址。
ua string (required) — 客户端设备的用户代理（User-Agent）字符串。
createdAt string — 会话创建时的时间戳。
updatedAt string (required) — 此会话最后活动的时间戳。
status 'online' | 'expired' | 'offline' — 会话的当前状态。
user UserSessionUser — 用户的详细信息。
userDid string (required) — 拥有该会话的用户的 DID。
visitorId string (required) — 访问者/设备的标识符。
passportId string | null (required) — 用户 Passport 的 ID。
extra object (required) — 附加元数据。
- walletOS 'android' | 'ios' | 'web' (required) — 所用钱包的操作系统。

UserSessionUser

包含与会话关联的用户的详细信息。

did string (required) — 用户的去中心化标识符（DID）。
fullName string (required) — 用户的全名。
email string (required) — 用户的电子邮件地址。
avatar string (required) — 用户头像图片的 URL。
pk string (required) — 用户的公钥。
role string (required) — 用户在应用程序中的角色（例如，'owner'、'admin'）。
roleTitle string (required) — 用户角色的显示标题。
sourceProvider 'wallet' | 'auth0' | 'nft' (required) — 用于身份验证的提供商。
sourceAppPid string | null (required) — 提供用户数据的应用程序的 PID。
remark string — 关于用户的任何备注或注释。

UserSessionList

用户会话的分页列表。

list UserSession[] (required) — 一个用户会话对象的数组。
paging object (required) — 一个包含分页详细信息的对象。
- page number (required) — 当前页码。
- pageSize number (required) — 每页的项目数。
- total number (required) — 项目总数。

UserSessionQuery

用于筛选和分页会话查询的对象。

page number (required) — 要检索的页码。
pageSize number (required) — 每页的会话数。
status 'online' | 'expired' | 'offline' — 按会话状态筛选。