メインコンテンツへスキップ

クレームのリクエスト

DID Connectセッションにおいて、「クレーム」とは、ユーザーのウォレットに対してリクエストする特定の情報やアクションのことです。これには、氏名やメールアドレスから、資産の所有権を証明する暗号署名まで、あらゆるものが含まれます。このガイドでは、ユーザーにクレームをリクエストするさまざまな方法について解説します。

すべてのクレームリクエストは、handlers.attach メソッドの claims プロパティ内で設定します。利用可能なクレームの種類とそのパラメータの完全なリストについては、クレームリファレンス を参照してください。

単一のクレームをリクエストする

最も簡単なユースケースは、単一の情報をリクエストする場合です。リクエストしたい特定のクレームを表す各キーを持つ claims オブジェクトを定義します。値は通常、クレームの定義オブジェクトを返す関数です。

例えば、ユーザーの氏名とメールアドレスを含むプロフィールをリクエストするには、次のように設定します。

Basic Profile Claim

javascript
handlers.attach({
  action: 'profile',
  claims: {
    // キー 'profile' はクレームの種類を指定します。
    // 値は、クレームのパラメータを返す関数です。
    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 クレームをリクエストしています。ウォレットはユーザーに氏名とメールアドレスの共有を促します。ユーザーが承認すると、onAuth コールバックが claims 配列で送信された情報を受け取ります。

複数のクレームをリクエストする

DID Connectでは、1回のセッションで複数の情報をリクエストできるため、非常に効率的です。これには、クレームが異なる種類か同じ種類かに応じて、2つの方法があります。

複数の異なる種類のクレーム

一度に複数の異なる種類のクレームをリクエストするには、claims オブジェクトにキーと値のペアを追加するだけです。例えば、同じセッションでユーザーのプロフィールと特定の資産の所有権証明を要求できます。

Multiple Different Claims

javascript
handlers.attach({
  action: 'multiple-claims',
  claims: {
    profile: () => ({
      fields: ['fullName', 'email'],
      description: '続行するには、氏名とメールアドレスを提供してください',
    }),
    asset: ({ userDid, extraParams }) => {
      // アセットクレームは、パラメータを動的に設定するための関数にすることができます
      return {
        description: '有効なNFTの所有権を証明してください',
        trustedIssuers: ['z1...', 'z2...'], // オプション: 信頼できるNFT発行者でフィルタリング
      };
    },
  },
  onAuth: async ({ claims, userDid }) => {
    // `claims` は、プロフィールとアセットクレームの両方の結果を含む配列です。
    const profile = claims.find(c => c.type === 'profile');
    const asset = claims.find(c => c.type === 'asset');
    console.log({ userDid, profile, asset });
  },
});

同じ種類の複数クレーム

同じ種類のクレームを複数リクエストする必要がある場合(例:ユーザーに2つの異なるメッセージへの署名を求める)、少し異なる構文が必要です。各リクエストに一意のキーを使用し、クレームの種類とその定義を2要素の配列として指定します。

2つの異なる signature クレームをリクエストする方法は次のとおりです。

Multiple Same-Type Claims

javascript
handlers.attach({
  action: 'multiple-signatures',
  claims: {
    // 'signText' は、この特定のリクエストの一意の識別子です。
    signText: [
      'signature', // 最初の要素は、文字列としてのクレームの種類です。
      {          // 2番目の要素は、クレームの定義オブジェクトです。
        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);
  },
});

動的クレーム

シナリオによっては、リクエストする必要のある情報がユーザーによって異なる場合があります。例えば、ユーザーがまだKYC(顧客確認)クレデンシャルを提出していない場合にのみ、それをリクエストしたい場合などです。これは、onConnect ライフサイクルコールバックと 動的クレーム を使用して実現できます。

onConnect コールバックは、ユーザーがQRコードをスキャンしてウォレットでDIDを選択した後、クレームがユーザーに送信される に実行されます。これにより、ユーザーのDID(userDid)にアクセスして、ビジネスロジックを実行できます。

Dynamic Claims with onConnect

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

  // この関数は、ウォレットが接続した後、クレームがリクエストされる前に実行されます。
  onConnect: async ({ userDid }) => {
    // 例:ユーザーがプロフィールを提供する必要があるかどうかを確認します。
    const userExists = await checkUserInDatabase(userDid);

    if (!userExists) {
      // 必要な情報をリクエストするためのクレームオブジェクトを返します。
      return {
        profile: () => ({
          fields: ['fullName', 'email'],
          description: '続行するにはプロフィールを作成してください',
        }),
      };
    }

    // クレームが不要な場合は、nullまたは空のオブジェクトを返します。
    return {};
  },

  onAuth: async ({ claims, userDid }) => {
    // `claims` には、動的にリクエストされたクレームの結果が含まれます(もしあれば)。
    if (claims.length > 0) {
      console.log('ユーザーが動的クレームを送信しました:', claims);
    }
  },
});

onConnect からクレームオブジェクトを返すことで、各ユーザーの特定のコンテキストに合わせてDID Connectセッションを調整し、よりインテリジェントで合理化された体験を生み出すことができます。

これでユーザーに情報をリクエストする方法がわかりました。次のステップは、ユーザーからの応答を処理する方法を学ぶことです。

次のステップ:ウォレットの応答を処理する

onAuth、onDecline、onErrorなどの様々なライフサイクルコールバックについて学び、セッションフロー全体を管理する方法をご覧ください。

続きを読む