個人資料聲明

個人資料聲明（Profile Claim）用於從使用者的 DID 錢包中請求個人資訊。這是許多應用程式的基礎步驟，透過在使用者明確同意下安全地獲取使用者資料，來實現使用者註冊、個人化體驗和通訊等功能。

結構

profile 聲明物件使用以下參數進行設定：

參數	類型	描述
`description`	`string`	必要。在使用者錢包中顯示給使用者的訊息，解釋為何請求其個人資料。例如：「請提供您的個人資料以建立帳戶。」
`items`	`string[]`	一個指定要請求的個人資料欄位的陣列。預設為 `['fullName']`。請參閱下方的「可用的個人資料欄位」表格以了解所有選項。關鍵字 `fields` 也可以作為 `items` 的別名使用。
`meta`	`any`	選用。任何您想與此聲明關聯的自訂元資料。這不會被發送到錢包，但可以在您的應用程式邏輯中使用。

可用的個人資料欄位

您可以在 items 陣列中請求以下欄位的任意組合：

欄位	描述
`did`	使用者的去中心化識別碼。
`fullName`	使用者的全名。
`email`	使用者的電子郵件地址。
`phone`	使用者的電話號碼。
`signature`	證明 DID 所有權的簽名。
`avatar`	使用者頭像圖片的 URL。
`birthday`	使用者的出生日期。
`url`	使用者個人網站或個人資料的 URL。

範例：請求使用者姓名和電子郵件

以下是如何設定 DID Connect 處理程式來請求使用者的全名和電子郵件地址。這是一個用於簡單登入或註冊流程的常見模式。

DID Connect Handler

const { WalletHandlers } = require('@arcblock/did-connect');

const handlers = new WalletHandlers({
  authenticator,
  // ... 其他設定
});

app.get('/api/auth/login', handlers.createAuthUrl({
  claims: {
    profile: {
      description: '請提供您的姓名和電子郵件以進行註冊。',
      items: ['fullName', 'email'],
    }
  },
  onAuth: async ({ userDid, userPk, claims }) => {
    // 'claims' 陣列將包含使用者的個人資料
    const profileData = claims.find(c => c.type === 'profile');
    console.log('使用者 DID:', userDid);
    console.log('個人資料:', profileData);

    // TODO: 使用提供的資訊在您的資料庫中尋找或建立使用者
  }
}));

在此範例中：

我們在 claims 物件中定義了一個 profile 聲明。
description 為使用者在其錢包中提供了上下文。
items 陣列指定我們需要 fullName 和 email。
onAuth 回呼函式接收錢包的回應，其中包含一個含有請求的個人資料資訊的 claims 陣列。

錢包回應

使用者在他們的 DID 錢包中批准請求後，您的 onAuth 回呼函式將會收到一個包含所請求資料的 payload。claims 陣列將持有一個類型為 profile 的物件，其中包含使用者的資訊。

Wallet Response Example

{
  "userDid": "z8ia29UsENBg6tLZUKi2HABj38Cw1LmHZocbQ",
  "userPk": "...",
  "claims": [
    {
      "type": "profile",
      "fullName": "Alice",
      "email": "alice@example.com",
      "meta": {}
    }
  ],
  "challenge": "...",
  "status": "ok"
}

您的應用程式接著可以使用這些資料來建立帳戶、個人化使用者體驗或執行其他所需的操作。

下一步

透過個人資料聲明辨識使用者後，您可能需要為安全敏感的操作驗證他們對 DID 的控制權。簽名聲明是實現此目的的完美工具。