ベストプラクティス

年齢ゲートのベストプラクティス

常に年齢ゲート要件をチェック

年齢情報を収集する前に、常にプレイヤーの管轄区域で/age-gate/get-requirementsを呼び出します。これにより、以下が保証されます：

必要な場合にのみ年齢ゲートを表示する（shouldDisplay = true）
管轄区域で承認された年齢収集方法のみを使用する
年齢閾値（デジタル同意年齢、法的年齢、最小年齢）を理解する
年齢保証が必要かどうかを知る

すべての年齢ゲートチェックレスポンスを処理

/age-gate/checkを呼び出す場合、3つの可能なステータスすべてを処理します：

PROHIBITED: プレイヤーが最小年齢未満 - アクセスを完全にブロック
CHALLENGE: プレイヤーが親の同意を必要とする - チャレンジを作成して表示
PASS: プレイヤーは続行できる - セッションを取得または作成

レスポンスステータスをチェックせずにプレイヤーが続行できると想定しないでください。

VPCとチャレンジのベストプラクティス

チャレンジIDを永続的に保存

/age-gate/checkからCHALLENGEステータスが返された場合、チャレンジIDをローカルストレージまたはサーバーに保存します。これにより、以下が可能になります：

同意が付与される前にプレイヤーが戻った場合、同意フローを再開する
後続の訪問で同じチャレンジ情報（QRコード、OTP）を表示する
/challenge/getを使用してチャレンジの詳細を取得する

チャレンジステータスにwebhooksを使用（推奨）

ポーリングの代わりに、Challenge.StateChangeイベントを受信するwebhookを設定します。Webhooksは以下を提供します：

同意が付与または拒否されたときのリアルタイム更新
API呼び出しの削減とパフォーマンスの向上
より信頼性の高いステータストラッキング

ポーリングを使用する必要がある場合、適切なレート制限を実装します：

/challenge/get-statusへの呼び出しの間は最低5秒
HTTP 429レスポンスを常にチェックし、適切な再試行ロジックを実装する
適切なタイムアウト制限を設定する

信頼できる大人に効果的に通知

チャレンジが作成されたとき、信頼できる大人が同意を完了するための複数の方法を提供します：

メール通知: メールアドレスが利用可能な場合、/challenge/send-emailを呼び出す
QRコード表示: チャレンジレスポンスで返されたQRコードURLを表示する
OTP入力: 手動入力用のワンタイムパスワードを表示する

カスタマーサービスの目的で、チャレンジステータスレスポンスからapproverEmailを保存します。

セッション管理のベストプラクティス

セッションを適切にキャッシュ

セッションはローカルストレージまたはクラウドストレージにキャッシュし、プレイヤーのアカウントに関連付ける必要があります。セッションは、以下の場合にのみ変更されます：

親が権限を更新したとき
プレイヤーが次の年齢カテゴリに「年齢が上がった」とき
セッションが親またはプレイヤーによって削除されたとき

ETagsを使用してセッション取得を効率化

/session/get APIは、etagパラメータを使用した条件付きリクエストをサポートします。キャッシュされたセッションからETagを含めます：

セッションが変更されていない場合、APIはHTTP 304（Not Modified）を返す
これにより、不要なデータ転送が削減され、パフォーマンスが向上する
ゲームが再起動するたびにセッションを常に更新する

セッションwebhooksを実装

セッション関連のイベントを受信するwebhookを設定します：

Session.ChangePermissions: 親によって権限が変更されたときに送信される
Session.Delete: セッションが削除されたときに送信される

これにより、ポーリングなしでリアルタイム更新が提供され、ゲームが権限の変更を即座に反映することが保証されます。

セッションアップグレードを適切に処理

プレイヤーが親の同意を必要とする追加の権限をリクエストする場合：

/session/upgradeを使用して、新しい権限のチャレンジを作成する
権限アップグレードウィジェットを使用して、同意ワークフローを処理する
webhooksまたはポーリングを通じてセッションの変更を監視し、アップグレードが承認されたときに検出する

権限のベストプラクティス

権限ステータスを尊重

各権限のenabledとmanagedByフィールドの両方を常にチェックします：

enabled: true: 機能をプレイヤーに対して有効にできる
enabled: false: 機能をオフにする必要がある
managedBy: PLAYER: プレイヤー自身が有効/無効にできる
managedBy: GUARDIAN: 信頼できる大人のみが有効/無効にできる
managedBy: PROHIBITED: 機能が許可されない - UIから完全に削除する

権限をゲーム機能に正しくマッピング

各k-ID権限がゲーム内の対応する機能に適切にマッピングされていることを確認します。権限は、以下へのアクセスを制御する必要があります：

年齢制限のあるコンテンツ
親の同意を必要とする機能
データ収集機能
通信機能

Compliance Studioで権限を設定して、ゲームの機能セットに一致させます。

セキュリティの推奨事項

サーバー専用のAPI呼び出し

重要

すべてのウィジェットURL生成エンドポイントは、サーバーからのみ呼び出す必要があり、クライアント側のコードから直接呼び出さないでください。

k-ID APIキーは保護する必要がある秘密の認証情報です：

APIキーを安全に保存するためにシークレットマネージャーを使用する
APIキーを公開しない - フロントエンドJavaScript、モバイルアプリコード、またはクライアント向けコードに含めない
APIキーをクライアントデバイスまたはクライアント側ストレージに保存しない

ターゲットオリジン設定

CDKは、Compliance Studioでターゲットオリジンを設定する機能を提供し、どのドメインがウィジェットを埋め込めるかを制御します。この設定は、Content Security Policyのframe-ancestorsディレクティブを制御します。オプションのセキュリティ対策として、リスク許容度を評価し、セキュリティ要件に基づいてターゲットオリジン制限を実装するかどうかを決定することを推奨します。

設定オプション：

特定のドメイン: 本番環境用に正確なドメインを設定（たとえば、https://yourgame.com）
ワイルドカードサブドメイン: サブドメインにワイルドカードパターンを使用（たとえば、https://*.yourgame.com）
無制限: 無制限の埋め込みのために空のままにするか*に設定（本番環境では推奨されません）

セキュリティ上のメリット： ターゲットオリジンは、攻撃者が悪意のあるサイトの透明なiframeにコンプライアンスフローを埋め込み、他のコンテンツをオーバーレイしてユーザーが誤って確認要素をクリックするようにだますことを防ぎます。

重要

実装に関する注意事項：

各環境（テスト/ライブ）に対して個別のターゲットオリジンを設定する
本番環境に移行する前に、すべての本番エンドポイントでターゲットオリジンが適切に設定されていることを確認してください。
ワイルドカードを使用しない限り、各サブドメインには独自のエントリが必要です

情報

ターゲットオリジン設定に関係なく、特定のk-IDページのみがiframeに埋め込むことができます（確認ページ、ウィジェット、VPCフロー）。他のすべてのk-IDページ（家族管理、アカウント設定）は、常にiframe埋め込みからブロックされます。

iframe権限

iframeのallow属性に必要な権限を常に含めてください：

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

権限の内訳：

camera - 顔年齢推定に必要（使用する場合）
payment - クレジットカード確認に必要（使用する場合）
publickey-credentials-create - AgeKey作成に必要（使用する場合）
publickey-credentials-get - AgeKey確認に必要（使用する場合）

オリジンの検証

受信メッセージのオリジンを常に検証してください：

window.addEventListener('message', (event) => {
  // 環境に基づいてオリジンを検証
  const validOrigins = [
    'https://family.k-id.com',        // ライブ環境
    'https://family.test.k-id.com'    // テスト環境
  ];
  
  if (!validOrigins.includes(event.origin)) {
    return; // 許可されていないオリジンからのメッセージを無視
  }
  
  // イベントを処理
  handleWidgetEvent(event.data);
});

アカウントシステム統合

製品コンテキストマッピング

複数のゲームにまたがるアカウントシステムにCDKを統合する場合：

Compliance Studioで各ゲームを独自のk-ID製品にマッピングする
グローバル権限のためにアカウントシステム自体用に別のk-ID製品を作成する
各製品コンテキストに対して正しいAPIキーが使用されていることを確認する
クロス製品セッション取得のために、アカウントシステムにセッションからkuidを保存する

複数製品のセッションキャッシュ

アカウントシステムで製品IDごとにセッションをキャッシュします：

k-ID製品IDをキャッシュキーとして使用する
新しいVPCフローをトリガーする前に既存のセッションをチェックする
製品のセッションが既に存在する場合、追加の同意なしでプレイヤーが続行できるようにする

管轄区域の処理

API呼び出しを行う際は、常に正しい管轄区域を渡します：

プレイヤーの場所またはIPアドレスから管轄区域を決定する
管轄区域固有の年齢閾値と要件を使用する
ゲームプレイ中に管轄区域が変更された場合、/session/update-jurisdictionを呼び出して処理する

年齢ゲートのベストプラクティス​

常に年齢ゲート要件をチェック​

すべての年齢ゲートチェックレスポンスを処理​

VPCとチャレンジのベストプラクティス​

チャレンジIDを永続的に保存​

チャレンジステータスにwebhooksを使用（推奨）​

信頼できる大人に効果的に通知​

セッション管理のベストプラクティス​

セッションを適切にキャッシュ​

ETagsを使用してセッション取得を効率化​

セッションwebhooksを実装​

セッションアップグレードを適切に処理​

権限のベストプラクティス​

権限ステータスを尊重​

権限をゲーム機能に正しくマッピング​

セキュリティの推奨事項​

サーバー専用のAPI呼び出し​

ターゲットオリジン設定​

iframe権限​

オリジンの検証​

アカウントシステム統合​

製品コンテキストマッピング​

複数製品のセッションキャッシュ​

管轄区域の処理​