チャレンジ

Consent Challengeは、子供がゲームまたはゲーム機能へのアクセスの同意を求める際に作成されます。確認済みの信頼できる大人が同意チャレンジに関連付けられると、チャレンジはk-ID Family Connectの信頼できる大人にアクセスリクエストとして表示されます。

チャレンジとは？

同意チャレンジは、プレイヤーの保護者の同意リクエストを表します。プレイヤーの年齢が現在の管轄区域で検証可能な保護者の同意（VPC）を必要とする場合、k-IDはチャレンジを作成し、プレイヤーがゲームまたは機能にアクセスする前に信頼できる大人によって承認される必要があります。

チャレンジの作成

チャレンジは、以下の場合に自動的に作成されます：

• プレイヤーの年齢が保護者の同意を必要とする場合（/age-gate/check APIによって決定される）
• プレイヤーが保護者の同意を必要とする権限へのアクセスをリクエストする場合（/session/upgrade APIを通じて）

チャレンジIDはAPIレスポンスで返され、ゲームによってプレイヤーに関連付けられたローカルストレージまたはクラウドストレージに保存される必要があります。

チャレンジ情報

チャレンジが作成されると、APIは以下を返します：

• challengeId: チャレンジの一意の識別子
• oneTimePassword: 親が同意ポータルにアクセスするために入力できるパスワード
• url: モバイルアクセスを簡単にするためにQRコードとして表示できるURL

同意チャレンジウィンドウには、QRコード、ワンタイムパスワード、および同意を付与できる親または保護者のメールアドレスを入力できる入力フィールドを表示する必要があります。

チャレンジステータス

同意チャレンジウィンドウを表示した後、ゲームはチャレンジが正常に完了するまで待機する必要があります。Challenge.StateChangeイベントをリッスンするWebhooksの使用を強く推奨します。フォールバックオプションとして、チャレンジIDで/challenge/get-status APIを定期的に呼び出すことによるポーリングが利用できます。

チャレンジステータスは次のいずれかになります：

• PASS: 信頼できる大人によって同意が付与された
• FAIL: リクエストが拒否された
• PENDING: チャレンジがまだ応答を待っている
• POLL_TIMEOUT: ポーリングタイムアウトに達した（タイムアウト付きポーリングを使用する場合）

信頼できる大人への通知

同意チャレンジについて信頼できる大人に通知する方法はいくつかあります：

QRコードとワンタイムパスワード

チャレンジレスポンスには、QRコードとして表示できるURLとワンタイムパスワードが含まれます。親はどちらの方法でも同意ポータルに直接アクセスできます。

メール通知

プレイヤーによって親または保護者のメールアドレスが提供された場合、ゲームはこのメールアドレスを/challenge/send-email APIへのパラメータとして渡す必要があります。これにより、親が承認できるFamily Connectへのリンクが含まれた事前設定されたメールがアドレスに送信されます。このメールの設定オプションはCompliance Studioで提供されます。

同意の待機

ゲームは、同意が付与されるまでどのくらい待つか、その時間が経過した場合に何をするかを決定する必要があります。期間の選択は短い（10分）場合も長い（24時間以上）場合もあります。

この間、/challenge/get-status APIへの多くの呼び出しが行われる可能性があります。/challenge/get-statusへの呼び出しの間には、最低5秒の遅延が必要です。また、/challenge/get-statusはHTTPコード429を返す可能性があります。ゲームは、429レスポンスを処理する際に適切な再試行ロジックを実装する必要があります。

同意を待っている間、プレイヤーは何ができるか？

一部のゲームでは、親が同意を付与するまでプレイヤーがゲームを続行することを完全に停止することが適切であり、ウィンドウはモーダルである必要があります。他のゲームでは、信頼できる大人の同意がリクエストされている間、アクセスが拒否される前に、未成年のプレイヤーが一定時間続行することが許可されることが合理的な場合があります。この場合、信頼できる大人の同意を待っている間、ゲームはプレイヤーに関するデータを収集したり、同意が必要な可能性のある他の機能へのアクセスを提供したりしない責任があります。

保留中の同意チャレンジ

/age-gate/checkからCHALLENGEのステータスが返された場合、返されたチャレンジIDは、チャレンジがアクティブな間、ローカルストレージに保存する必要があります。ゲームが開始されたときにアクティブなチャレンジが存在すると、ゲームは以前と同じ同意チャレンジウィンドウを表示するように指示されます。ローカルストレージからチャレンジIDを取得した後、/challenge/get APIを呼び出して、ワンタイムパスワードとQRコードURLを含む現在のチャレンジに関する情報を取得し、チャレンジウィンドウを再度ユーザーに表示する必要があります。

チャレンジの有効期限と時間ベースの認証

同意チャレンジは通常、信頼できる大人が応答するまで対応可能な状態を維持しますが、生成された時間ベースの認証方法（たとえば、OTP、メールリンク）は期限切れになり、リフレッシュされます。一部の管轄区域やインテグレーターの設定では、チャレンジ自体に厳格な期限が課され、それを過ぎるとチャレンジに対応できなくなります（下記の チャレンジURLとメールリンクの有効期限 を参照）。k-IDは、使いやすさを維持しながらセキュリティを確保するために、時間ベースの認証メカニズムを実装しています。

ワンタイムパスワード（OTP）

各チャレンジは、親が同意ポータルにアクセスするために使用できる一意のOTPを作成します。これらのOTPは：

• チャレンジが作成されたときに自動的に生成される
• 1時間有効
• /challenge/generate-otp APIを通じて更新される

QRコードURL

チャレンジレスポンスには、モバイルアクセスを簡単にするためにQRコードとして表示できるURLが含まれます。このURLは：

• 埋め込みOTPを含む
• OTPと一緒に期限切れになる（1時間）
• 親にシームレスなモバイルエクスペリエンスを提供する

チャレンジURLとメールリンクの有効期限

チャレンジ作成エンドポイント（/age-gate/check や /session/upgrade など）から返されるチャレンジURLと、/challenge/send-email で送信されるリンクは、同じ暗号署名されたチャレンジJWTを共有しています。JWTの exp クレームがリンクの有効期間を決定します。

• ライブモード： チャレンジURLは作成後 2週間 で期限切れになります。
• テストモード： チャレンジURLは作成後 7分 で期限切れになります。短い有効期間は意図的なもので、2週間待たずに期限切れURLの処理を試せるようにするためです。テストモードの詳細は Testing を参照してください。

これらはデフォルトの有効期間です。一部の管轄区域では、チャレンジ自体により短い規制上の期限が課されます：

開かずに既存のURLがまだ使用可能かを確認するには、JWTをデコードして標準の exp クレームを確認してください。

チャレンジがまだ期限内であれば、リンクやOTPが期限切れになっても新しいチャレンジを作成する必要はありません。代わりにアクセス方法をリフレッシュしてください：

• 同じ challengeId で /challenge/get を呼び出すと、アクティブなチャレンジの新しいURLとOTPを取得できます。
• メールリンクを再送するには、/challenge/send-email を再度呼び出します。

チャレンジ自体が期限を過ぎた場合（たとえば作成から24時間を超えたインドネシアの同意チャレンジ）、アクセス方法をリフレッシュしても解決しません。/challenge/generate-otp は通常どおり新しいワンタイムパスワード（通常どおり1時間有効）を発行し、/challenge/get と /challenge/send-email も引き続きURLを返すかメールリンクを送信します。しかし、いずれも期限を過ぎたチャレンジを完了することはできません。信頼できる大人がコードを入力するかリンクを開くと、同意ポータルには「リクエストの有効期限が切れました」と表示されます。新しい同意リクエストを開始するには、代わりに新しいチャレンジを作成してください。

ベストプラクティス

k-IDの時間ベースの認証を実装する場合：

1. 期限切れを積極的に監視し、反応的ではなく
2. 認証情報が期限切れになったときに適切な劣化を実装する
3. タイムアウトステータスについて明確なユーザーフィードバックを提供する
4. テスト環境でタイムアウトシナリオを徹底的にテストする
5. 更新操作中のネットワーク中断などのエッジケースを計画する

信頼できる大人のメールアドレスの取得

同意が付与された場合、親のメールアドレスは/challenge/get-statusのレスポンスのapproverEmailフィールドで返されます。これは、将来のカスタマーサービスケースで使用するためにゲームによって保存できます。

チャレンジのテスト

Family Connectで信頼できる大人の同意フローを経ることなく、APIで信頼できる大人の同意をテストすることができます。これを行うには、/test/set-challenge-statusを呼び出して同意チャレンジのステータスを設定できます。ステータスをPASSまたはFAILに割り当てることができます。本文の一部としてageとjurisdictionも渡す必要があります。オプションで、approverEmailフィールドで返すメールを渡すことができます。同じchallengeIdを使用した/challenge/get-statusへの次の呼び出しは、割り当てた情報を返します。これにより、ゲーム内で信頼できる大人の同意シナリオを迅速にテストできます。