保護書の同意を求めること

/age-gate/check の status フィールドで CHALLENGE の値が返された場合、レスポンスの challengeId フィールドには、k-IDエンジンの Consent Challenge のIDが含まれています。この時点で、プレイヤーが親の同意を求めるためのウィンドウを表示する必要があります。

同意チャレンジ

Consent Challengeは、プレイヤーが同意を求めるリクエストを表します。Consent Challengeに関する追加情報は、/age-gate/check APIから返されます。

/age-gate/check APIは、親がhttps://k-id.com/code に直接アクセスして入力できるワンタイムパスワードと、QRコードとして表示できるURLを返します。Consent Challengeウィンドウには、QRコードとワンタイムパスワード、および同意を与えることができる保護者のメールアドレスをプレイヤーが入力できるフィールドを表示する必要があります。

同意チャレンジウィンドウを表示した後、ゲームは/age-gate/checkのレスポンスで返されたチャレンジIDを使って、定期的に/challenge/await APIを呼び出す必要があります。保護者はファミリーポータルで同意リクエストを受け取り、メールメッセージ、QRコード、またはウィンドウに表示されたURLにアクセスしてコードを入力することで承認できます。 同意リクエストは、指定されたタイムアウトパラメータの値（最大180秒）後にタイムアウトします。タイムアウトを0秒に設定することも可能で、その場合はブロックせずに現在のチャレンジのステータスを返します。呼び出しが返された後もチャレンジが保留中の場合、以降の呼び出しでレスポンスのstatusフィールドにはPOLL_TIMEOUTの値が表示されます。保護者ポータルを介して同意が与えられた場合、呼び出しはPASSのステータスで返され、リクエストが拒否された場合はFAILで返されます。

保護者がk-ID保護者ポータルでQRコードまたはワンタイムパスワードを使用して同意を与えた場合、ゲームワークフローで他に何もする必要はありません。プレイヤーが保護者のメールアドレスを提供した場合は、このメールアドレスをパラメータとして/challenge/email APIに渡し、そのアドレスにリンク付きの事前設定されたメールを送信します。このリンクにより保護者はファミリーポータルにアクセスし、同意を承認できます。このメールの設定オプションはパブリッシャーポータルで提供されています。

Checking for consent in Unreal C++

void UKidWorkflow::CheckForConsent(const FString& ChallengeId, FDateTime StartTime, int32 Timeout, 
                        TFunction<void(bool, const FString &)> OnConsentGranted)
{
    const int ChallengeAwaitTimeout = 0;

    FString Url = FString::Printf(TEXT("%s/challenge/await?challengeId=%s&timeout=%d"), 
                *BaseUrl, *ChallengeId, ChallengeAwaitTimeout);

    HttpRequestHelper::GetRequestWithAuth(Url, AuthToken, 
            [this, ChallengeId, StartTime, Timeout, OnConsentGranted]
            (FHttpResponsePtr Response, bool bWasSuccessful)
    {
        bool bConsentGranted = false;

        if (bWasSuccessful && Response.IsValid())
        {
            TSharedPtr<FJsonObject> JsonResponse;
            TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(Response->GetContentAsString());
            if (FJsonSerializer::Deserialize(Reader, JsonResponse))
            {
                FString Status = JsonResponse->GetStringField(TEXT("status"));

                if (Status == TEXT("PASS"))
                {
                    FString SessionId = JsonResponse->GetStringField(TEXT("sessionId"));

                    FString ApproverEmail = JsonResponse->GetStringField(TEXT("approverEmail"));

                    // At this point, the player has been granted consent and 
                    // the email of the parent or guardian who granted consent is available
                    // in the approverEmail field. This can be used for customer service 
                    // requests later.
                    //
                    StoreParentEmailForLaterUse(SessionId, ApproverEmail);

                    OnConsentGranted(true, SessionId);
                    return;
                }
                else if (Status == TEXT("FAIL"))
                {
                    OnConsentGranted(false, TEXT(""));
                    return;
                }
            }

            FDateTime CurrentTime = FDateTime::UtcNow();
            FTimespan ElapsedTime = CurrentTime - StartTime;

            // Retry if the elapsed time is less than the overall timeout
            if (ElapsedTime.GetTotalSeconds() < Timeout)
            {
                GetWorld()->GetTimerManager().SetTimer(ConsentPollingTimerHandle, [this, ChallengeId, StartTime, Timeout, OnConsentGranted]()
                {
                    CheckForConsent(ChallengeId, StartTime, Timeout, OnConsentGranted);
                }, ConsentPollingInterval, false);
            }
            else
            {
                OnConsentGranted(false, TEXT(""));
            }
        }
        else
        {
            OnConsentGranted(false, TEXT(""));
        }

    });
}

保護者の同意を待っている間にプレイヤーができること

一部のゲームでは、保護者が同意を与えるまでプレイヤーがゲームを続行できないようにし、ウィンドウをモーダルにすることが適切です。別のゲームでは、未成年のプレイヤーが保護者の同意を求めている間に一定期間プレイを許可され、その後アクセスが拒否されることが合理的と考えられる場合もあります。この場合、保護者の同意を待っている間、ゲームはプレイヤーに関するデータの収集や、同意が必要な他の機能へのアクセスを避ける責任があります。

保留中の同意チャレンジ

アクティブなチャレンジが存在する場合、以前と同じ同意チャレンジウィンドウを表示するようにゲームを誘導します。ローカルストレージからチャレンジIDを取得した後、/challenge/get APIを呼び出して現在のチャレンジに関する情報（ワンタイムパスワードやQRコードURLなど）を取得し、チャレンジウィンドウを再度ユーザーに表示する必要があります。

保護者の応答を待つ時間

ゲームは、同意が得られるまでどのくらいの時間待つか、そしてその時間が経過した場合に何をすべきかを判断する必要があります。待機時間の選択は短い場合（10分）もあれば、長い場合（24時間以上）もあります。この期間中に、多くの/challenge/await API呼び出しが行われる可能性があります。/challenge/awaitの呼び出しの間には、最低でも5秒の遅延を設ける必要があります。また、/challenge/awaitはHTTPコード429と共にRetry-AfterヘッダーをHTTPレスポンスで返すことがあります。ゲームはk-ID API呼び出しを行う際に、このヘッダーを常に確認する必要があります。

同意チャレンジの有効期限切れ

同意チャレンジは7日後に期限切れとなることが想定されます。

保護者のメールアドレスの取得

同意が与えられ、/challenge/await の status フィールドで PASS が返された場合、保護者のメールアドレスが approverEmail フィールドに返されます。これをゲーム内で保存し、将来のカスタマーサービス対応に使用することができます。

保護者同意のテスト

ファミリーポータルでの保護者同意フローを経ずに、API内で保護者同意をテストすることが可能です。このためには、/test/set-challenge-status を呼び出して Consent Challenge のステータスを設定します。ステータスは PASS または FAIL に設定できます。リクエストボディには age と jurisdiction も渡す必要があります。オプションで、approverEmail フィールドに返すメールアドレスも渡すことができます。同じ challengeId を使用して次に challenge/await を呼び出すと、設定した情報が返されます。これにより、ゲーム内で保護者同意シナリオを迅速にテストすることができます。