跳到主要內容

請求 Claim

在 DID Connect 會話中，「claim」是您向使用者錢包請求的特定資訊或操作。這可以是從姓名、電子郵件到證明資產所有權的加密簽名等任何內容。本指南將帶您了解向使用者請求 claim 的不同方式。

所有 claim 請求都在 handlers.attach 方法的 claims 屬性中進行設定。有關可用 claim 類型及其參數的完整列表，請參閱 Claims 參考文件。

請求單一 Claim

最直接的使用情境是請求單一資訊。您需要定義一個 claims 物件，其中每個鍵值代表您想請求的特定 claim。其值通常是一個回傳 claim 定義物件的函式。

例如，若要請求包含使用者全名和電子郵件的個人資料，您可以如下設定：

Basic Profile Claim

javascript
handlers.attach({
  action: 'profile',
  claims: {
    // 鍵值 'profile' 指定了 claim 類型。
    // 其值是一個回傳 claim 參數的函式。
    profile: () => ({
      fields: ['fullName', 'email'],
      description: '請提供您的姓名和電子郵件以繼續',
    }),
  },

  onAuth: async ({ userDid, claims }) => {
    // 'claims' 陣列包含使用者提交的資料。
    try {
      const profile = claims.find((x) => x.type === 'profile');
      console.info('login.success', { userDid, profile });
    } catch (err) {
      console.error('login.error', err);
    }
  },
});

在此範例中，我們請求一個 profile claim。錢包會提示使用者分享其全名和電子郵件。一旦使用者批准，onAuth 回呼函式就會在 claims 陣列中收到提交的資訊。

請求多個 Claim

DID Connect 允許您在單一會話中請求多項資訊，這非常高效。根據 claim 的類型是否相同，有兩種方法可以實現。

多個不同類型的 Claim

若要一次請求多個不同類型的 claim，只需在 claims 物件中新增更多的鍵值對即可。例如，您可以在同一個會話中請求使用者的個人資料和特定資產的所有權證明。

Multiple Different Claims

javascript
handlers.attach({
  action: 'multiple-claims',
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: '請提供您的姓名和電子郵件以繼續',
    }),
    asset: ({ userDid, extraParams }) => {
      // asset claim 可以是一個函式，用以動態設定參數
      return {
        description: '請證明您對一個有效 NFT 的所有權',
        trustedIssuers: ['z1...', 'z2...'], // 選用：依可信任的 NFT 發行者進行篩選
      };
    },
  },
  onAuth: async ({ claims, userDid }) => {
    // `claims` 是一個陣列，同時包含 profile 和 asset claim 的結果。
    const profile = claims.find(c => c.type === 'profile');
    const asset = claims.find(c => c.type === 'asset');
    console.log({ userDid, profile, asset });
  },
});

多個相同類型的 Claim

如果您需要請求多個相同類型的 claim（例如，要求使用者簽署兩則不同的訊息），您需要使用稍微不同的語法。您為每個請求使用一個唯一的鍵，並將 claim 類型及其定義以一個包含兩個元素的陣列形式提供。

以下是如何請求兩個不同的 signature claim：

Multiple Same-Type Claims

javascript
handlers.attach({
  action: 'multiple-signatures',
  claims: {
    // 'signText' 是此特定請求的唯一識別碼。
    signText: [
      'signature', // 第一個元素是作為字串的 claim 類型。
      {          // 第二個元素是 claim 的定義物件。
        type: 'mime:text/plain',
        data: '我同意服務條款。',
        description: '請簽署此文本以繼續',
      },
    ],
    // 'signHtml' 是另一個唯一識別碼。
    signHtml: [
      'signature',
      {
        type: 'mime:text/html',
        data: `<h2>交易摘要</h2><p>金額：100 ABC</p>`,
        description: '請簽署以確認交易',
      },
    ],
  },
  onAuth: async ({ claims, userDid }) => {
    // `claims` 將包含兩個簽名請求的結果。
    console.log('使用者已簽署的訊息：', claims);
  },
});

動態 Claim

在某些情境下，您需要請求的資訊取決於使用者是誰。例如，您可能只想在使用者先前未提供過 KYC（了解您的客戶）憑證時才請求它。這可以透過使用 onConnect 生命週期回呼函式並搭配 動態 claim 來實現。

The onConnect 回呼函式會在使用者掃描 QR code 並在錢包中選擇 DID 之後，但在 claim 發送給他們之前執行。這讓您能存取使用者的 DID (userDid) 來執行業務邏輯。

Dynamic Claims with onConnect

javascript
handlers.attach({
  action: 'dynamic-claims',

  // 此函式在錢包連接後、請求 claim 之前執行。
  onConnect: async ({ userDid }) => {
    // 範例：檢查使用者是否需要提供個人資料。
    const userExists = await checkUserInDatabase(userDid);

    if (!userExists) {
      // 回傳一個 claims 物件以請求所需的資訊。
      return {
        profile: () => ({
          fields: ['fullName', 'email'],
          description: '請建立您的個人資料以繼續',
        }),
      };
    }

    // 如果不需要任何 claim，則回傳 null 或一個空物件。
    return {};
  },

  onAuth: async ({ claims, userDid }) => {
    // `claims` 將包含動態請求的 claim 結果（如果有的話）。
    if (claims.length > 0) {
      console.log('使用者提交了動態 claim：', claims);
    }
  },
});

透過從 onConnect 回傳一個 claims 物件，您可以為每位使用者的特定情境量身打造 DID Connect 會話，從而創造更智慧、更流暢的體驗。

現在您已經知道如何向使用者請求資訊，下一步是學習如何處理他們的回應。

下一步：處理錢包回應

探索各種生命週期回呼函式，如 onAuth、onDecline 和 onError，以管理整個會話流程。

閱讀更多