データ通知

k-ID APIを使用してカスタムVPCフローを構築する場合、データ通知ウィジェットを使用して製品のデータ通知を表示し、ユーザーの同意を収集できます。ウィジェットは、管轄区域に適した開示を表示し、同意承認ワークフローを処理します。

データ通知の一般的な情報（必要な場合と保存されるデータを含む）については、コアコンセプトセクションのデータ通知を参照してください。

データ通知ウィジェットURLの生成

/widget/generate-direct-notices-url APIを呼び出して、データ通知ウィジェットURLを作成します。これにより、ユーザーがデータ通知を表示および承認するための一意のURLが返されます。

リクエストの例

POST /api/v1/widget/generate-direct-notices-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "jurisdiction": "US-CA",
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
}

リクエストパラメータ

プロパティ	説明	必須?
`jurisdiction`	データ通知を表示する管轄区域	はい
`sessionId`	プレイヤーのセッションID（利用可能な場合）	いいえ

レスポンスの例

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/widget?token=eyJhbGciOiJFUzM4NCIs..."
}

ウィジェットの埋め込み

返されたURLを使用して、Webサイトまたはアプリにiframeを作成します。ユーザーはこのインターフェースを通じてデータ通知を表示し、同意を提供します：

<iframe 
  src="WIDGET_URL" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

同意結果の受信

データ通知の同意は、セッションの一部として追跡されます。データ通知が承認されると、同意がセッションに記録されます。/session/get APIを呼び出してセッションを確認することで、データ通知の同意ステータスを確認できます。

リアルタイム更新については、セッション関連のイベントをリッスンすることもできます：

JavaScriptイベント（クライアント側）

イベント構造の詳細については、Widget.DataNotices.ConsentApprovedを参照してください。

データ通知ウィジェットがiframeに埋め込まれている場合、ウィジェットからのウィンドウメッセージをリッスンできます：

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // ウィジェット完了イベントを処理
  if (message.eventType === 'Widget.DataNotices.ConsentApproved') {
    // データ通知が承認された
    console.log('Data notices accepted:', message.data.jurisdiction);
    handleConsentAccepted();
  }
});

イベントの例：

{
  "eventType": "Widget.DataNotices.ConsentApproved",
  "data": {
    "jurisdiction": "US"
  }
}

Webhooks（サーバー側）

webhookイベント構造の詳細については、Session.ChangePermissionsを参照してください。

セッション関連のイベントを受信するwebhookエンドポイントを設定します。データ通知の同意が更新されると、セッションの変更がSession.ChangePermissionsイベントに反映されます。詳細については、Webhooksを参照してください。