はじめにクイックスタートガイド

機能利用時の年齢保証

Adaptive Accessと/session/upgradeを使い、ユーザーが保護された機能に到達したときにのみ年齢の証明を求めます。

このガイドでは、Adaptive Accessの機能側である機能レベルの年齢保証を設定します。ユーザーは通常どおりサインアップします。ユーザーが、その市場で確認済み年齢が必要な機能に到達すると、アプリはk-IDにその機能の解除を依頼し、ユーザーはまだ証明していない場合にのみ年齢を証明します。設定、セッション、チェック、結果、機能の解除という1つの流れで、Compliance Studioの設定から解除された機能までを進めます。

代わりにサインアップ時に証明を求めるには、エントリー時の年齢保証に従ってください。

AIコーディングエージェントと統合する

公式の Agent Skills では、セッション、権限、年齢保証チャレンジ、webhookなど、AI支援での統合を扱います。

前提条件

  1. プロダクトで制限する機能が権限として登録された、Compliance Studioの CDKプロダクト。プロダクト設定: API設定を参照してください。
  2. プロダクトの開発者設定から取得した テストモードのAPIキー。テストモードの呼び出しは https://game-api.test.k-id.com に送信されます。テストを参照してください。
  3. Challenge.StateChange と Session.ChangePermissions イベントを受信する webhookエンドポイント。Webhooksを参照してください。
  4. カスタム年齢ゲート、VPCウィジェット、またはエントリー時の年齢保証から取得した、ユーザーの CDKセッション。

APIキーはサーバー上に保管してください

このガイドのすべてのk-ID API呼び出しはサーバー間で行います。APIキーをブラウザやアプリに送信しないでください。

ステップ1:機能レベルのアクセスを有効にする

新しいプロダクトは、機能レベルのアクセスが はい に設定された状態で始まります。既存のプロダクトの場合、または設定を確認する場合:

  1. Compliance Studioでプロダクトを開き、エンジンとオーバーライド を選択します。
  2. グローバルルールの編集 を選択します。
  3. 機能レベルのアクセス で、CDKのルールをすべての機能に適用する場合は はい を、個々の機能を上書きする場合は はい(変更あり) を選択します。
  4. 変更を保存 を選択し、続いて テスト環境にプッシュ を選択します。

機能ごと・市場ごとのルールについては、Adaptive Accessの設定を参照してください。

ステップ2:確認済み年齢が必要な機能を見つける

GET /session/get でユーザーのセッションを読み取ります。確認済み年齢が必要な権限は verifiedAgeThreshold を持っています:

{
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
  "permissions": [
    {
      "name": "loot-boxes-paid-gameplay-impacting",
      "enabled": false,
      "managedBy": "PLAYER",
      "verifiedAgeThreshold": 18
    }
  ]
}

各機能の表示方法は、権限だけから判断します:

権限表示するもの
enabled: true解除された機能
managedBy: "PLAYER"、verifiedAgeThreshold あり、enabled: false年齢を確認して解除するよう促すプロンプト付きの機能
managedBy: "PROHIBITED"何も表示しない。ユーザーは権限の最低年齢を下回っており、どのチェックでも解除できません。
managedBy: "GUARDIAN"保護者に依頼するよう促すプロンプト付きの機能。ユーザーが権限の最低年齢以上で閾値未満の場合、保護者が同意できます。セッションと権限の管理を参照してください。

閾値や市場をハードコードしないでください。これらはユーザーの市場に対するCDKのルールとCompliance Studioの設定から決まり、コードを変更しなくても変わる可能性があります。

ステップ3:k-IDに機能の解除を依頼する

ユーザーが機能を選択したら、サーバーからその権限を指定して POST /session/upgrade を呼び出します。チェックがiframeの外で開かれる場合は、リダイレクトURLを含めてください。プラットフォーム年齢シグナルがある場合はそれも含めます。閾値以上の信頼できるシグナルがあれば、チェックなしで機能が解除されます。

POST /api/v1/session/upgrade
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ],
  "options": {
    "redirectUrl": "https://mygame.com/upgrade/return"
  }
}

この呼び出しでは、verifiedAgeThreshold を持つ権限のみをリクエストしてください。閾値を持つ権限と持たない権限を混在させたリクエストは 400 を返します。

異なる年齢であっても、複数の閾値権限を一度にリクエストできます。ユーザーの確認は1回で済みます。チェックはリクエストされた最も高い年齢で判定されるため、リクエストされたすべての権限が解除されるか、どれも解除されないかのどちらかです。異なる年齢の権限をリクエストするを参照してください。

ステップ4:レスポンスを処理する

レスポンスには常に session が含まれ、ユーザーが確認を行う必要がある場合、または保護者が承認する必要がある場合にのみ challenge が含まれます:

const result = await response.json();

if (!result.challenge) {
  // チェックは不要:プラットフォームシグナルまたはセッションの既存の
  // ageVerification がすでに年齢を証明しているか、リクエストされた権限を
  // ユーザーの年齢では解除できません。result.session から各権限の `enabled` の値を読み取ります。
  return unlockFrom(result.session);
}

if (result.challenge.type === "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE") {
  await saveChallenge(result.challenge.challengeId, result.session.sessionId);
  return showAgeCheck(result.challenge.url);
}

if (result.challenge.type === "CHALLENGE_SESSION_UPGRADE") {
  // ユーザーはリクエストされたすべての閾値を下回っているか、デジタル同意年齢未満のため、保護者が承認します。
  await saveChallenge(result.challenge.challengeId, result.session.sessionId);
  return showParentApproval(result.challenge.url);
}

年齢保証チャレンジは次のようになります:

{
  "session": {
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "permissions": [
      {
        "name": "loot-boxes-paid-gameplay-impacting",
        "enabled": false,
        "managedBy": "PLAYER",
        "verifiedAgeThreshold": 18
      }
    ]
  },
  "challenge": {
    "challengeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE",
    "url": "https://family.k-id.com/session/upgrade/age-assurance?token=..."
  }
}

ステップ5:チェックを表示する

challenge.url は保護者ではなくユーザーに表示します。ユーザーは、プロダクトの年齢保証の方法のいずれかで確認を行います。

Webでは、iframeに埋め込みます。カメラ、決済、AgeKeyの方法には allow 属性が必要です:

<iframe
  src="CHALLENGE_URL"
  width="100%"
  height="600"
  frameborder="0"
  allow="camera;payment;publickey-credentials-get;publickey-credentials-create">
</iframe>

モバイルでは、URLをシステムブラウザで開き、ステップ3のリダイレクトURLを処理します。モバイルアプリクイックスタートを参照してください。コンソールでは、ユーザーのスマートフォン用にURLをQRコードとして表示します。

ユーザーが完了すると、ページは Challenge.StateChange メッセージを親ウィンドウにポストします。これはiframeを閉じるために使用し、機能の解除には使用しないでください。

ステップ6:サーバーで結果を取得する

Challenge.StateChange webhookを使用するか、GET /challenge/get-status をポーリングして、サーバーでk-IDから結果を読み取ります:

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": 42,
    "type": "CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE",
    "status": "PASS",
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187"
  }
}
status対応
PASSステップ7に進みます。チェックによってセッションの権限が変わった場合、k-IDは Session.ChangePermissions も送信します。
FAIL機能はロックされたままです。ユーザーは後で別の /session/upgrade 呼び出しを通じて再試行できます。
IN_PROGRESS待機を続けます。

ステップ7:機能を解除する

GET /session/get を呼び出し、その権限が enabled: true になっている場合にのみ機能を有効にします。チャレンジのステータスだけで機能を解除しないでください。

セッションには ageVerification が含まれるようになります。同じかより低い年齢の機能に対する後続の /session/upgrade は別のチェックなしで許可されるため、ユーザーが年齢を証明するのは1回だけです。

ステップ8:テストする

テストモードで、CDKが確認済み年齢を要求する市場において保護された機能を利用できる年齢のユーザーのセッションを作成し、次の手順を行います:

  • 権限に verifiedAgeThreshold と enabled: false があることを確認する
  • /session/upgrade を呼び出し、チャレンジURLからチェックを完了する(テストモードのチャレンジURLは7分で期限切れになります)
  • webhookが status: PASS を含む Challenge.StateChange を受信することを確認する
  • /session/get が enabled: true の権限を返し、セッションに ageVerification があることを確認する
  • 同じ権限について再度 /session/upgrade を呼び出し、チャレンジが返されないことを確認する

次のステップ

On this page