メインコンテンツに移動

チャレンジ

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

チャレンジの作成​

親の同意を必要とする生年月日で/age-gate/checkを呼び出すと、チャレンジが自動的に作成されます。チャレンジ情報はレスポンスで返されます：

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

チャレンジ情報​

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

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

チャレンジの表示​

チャレンジの表示方法と表示する情報については、コアコンセプトセクションのチャレンジを参照してください。

信頼できる大人への通知​

同意チャレンジについて信頼できる大人に通知する方法はいくつかあります。通知方法の詳細については、コアコンセプトセクションのチャレンジを参照してください。

メール通知​

プレイヤーによって親または保護者のメールアドレスが提供された場合、チャレンジIDとメールアドレスで/challenge/send-emailを呼び出します：

POST /api/v1/challenge/send-email
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
  "email": "parent@example.com"
}

または、メールアドレスを指定せずに/challenge/send-emailを呼び出すことができ、APIはプレイヤーの権限を最も最近承認した信頼できる大人にメールを送信します。関連するメールアドレスが見つからない場合、APIはINVALID_EMAILエラーコードで応答します。

チャレンジステータスの確認​

同意チャレンジを表示した後、信頼できる大人が同意プロセスを完了するまで待機します。チャレンジステータスは2つの方法で確認できます：

Webhooks（推奨）​

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

Challenge.StateChangeイベントを受信するwebhookエンドポイントを設定します。詳細については、Webhooksを参照してください。

ポーリング​

チャレンジIDで/challenge/get-status APIを定期的にポーリングします：

GET /api/v1/challenge/get-status?challengeId=683409f1-2930-4132-89ad-827462eed9af
Authorization: Bearer your-api-key

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

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

PASSレスポンスの例​

{
  "status": "PASS",
  "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
  "approverEmail": "parent@example.com"
}

同意の待機​

この間、/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、メールリンク）は期限切れになります。ユーザーフロー内でk-IDが時間ベースの認証をどのように使用するかの詳細については、チャレンジを参照してください。

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

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

チャレンジの詳細情報（チャレンジのテストを含む）については、コアコンセプトセクションのチャレンジを参照してください。