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) — 使用者通行證的 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) — 用戶端裝置的使用者代理字串。
createdAt string — 會話建立時的時間戳。
updatedAt string (required) — 此會話最後活動的時間戳。
status 'online' | 'expired' | 'offline' — 會話的目前狀態。
user UserSessionUser — 關於使用者的詳細資訊。
userDid string (required) — 擁有此會話的使用者的 DID。
visitorId string (required) — 訪客/裝置的識別碼。
passportId string | null (required) — 使用者通行證的 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' — 按狀態篩選會話。