请求家长同意

如果 /age-gate/check 的 status 字段返回值为 CHALLENGE，响应中的 challengeId 字段将包含 k-ID 引擎中的 Consent Challenge（同意挑战）ID。此时应显示一个窗口，允许玩家请求家长同意。

同意挑战

同意挑战表示玩家的同意请求。有关同意挑战的附加信息可通过 /age-gate/check API 返回。

/age-gate/check API 返回一个一次性密码，家长可以直接浏览至 https://k-id.com/code 输入密码，同时返回一个可呈现为二维码的 URL。同意挑战窗口应显示该二维码和一次性密码，以及一个输入框，允许玩家输入可以授予同意的家长或监护人的电子邮件地址。

显示同意挑战窗口后，游戏应周期性调用 /challenge/await API，并使用 /age-gate/check 响应返回的挑战 ID。家长会在家庭门户中收到同意请求，并可通过电子邮件消息、使用二维码，或通过输入窗口上显示的 URL 和代码进行批准。同意请求将在传递的 timeout 参数值后超时，最大为 180 秒。也可以传递 0 秒的 timeout，此时不会阻塞并直接返回挑战的当前状态。调用返回后，如果挑战仍在等待中，则后续调用的响应中的 status 字段值将为 POLL_TIMEOUT。如果通过 k-ID 家长门户授予了同意，调用将返回 PASS 状态；如果请求被拒绝，则返回 FAIL 状态。

如果家长或监护人通过二维码或一次性密码在 k-ID 家长门户中授予了同意，则游戏无需进行其他操作。如果玩家提供了家长或监护人的电子邮件地址，则游戏应将该地址作为参数传递给 /challenge/email API，系统会向该地址发送一封预配置的电子邮件，其中包含一个链接，家长可以通过该链接进入家庭门户进行批准。电子邮件的配置选项可在厂商门户中完成。

在 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"));

                    // 在此处，玩家已获得同意，
                    // 并且 approverEmail 字段中提供了授予同意的家长或监护人的电子邮件地址。
                    // 该地址可用于后续的客户服务请求。
                    //
                    StoreParentEmailForLaterUse(SessionId, ApproverEmail);

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

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

            // 如果经过时间小于总体超时时间，则重试
            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(""));
        }

    });
}

玩家在等待同意期间可以做什么？

对于某些游戏，在家长授予同意之前，完全阻止玩家继续游戏是合适的，此时窗口应为模态窗口。而在其他游戏中，允许未成年玩家在等待家长同意期间继续进行一段时间，随后才拒绝访问也是合理的。在这种情况下，游戏在等待家长同意期间应避免收集玩家数据，或提供其他可能需要同意的功能。

未完成的同意挑战

当 /age-gate/check API 返回的 status 为 CHALLENGE 时，返回的挑战 ID 应在挑战处于活动状态时存储在本地存储中。游戏启动时，活动挑战的存在会指示游戏返回显示之前的同意挑战窗口。从本地存储检索挑战 ID 后，应调用 /challenge/get API 以检索当前挑战的信息，包括一次性密码和二维码 URL，并再次向用户显示挑战窗口。

等待家长响应的时长

游戏必须确定等待家长授予同意的时间长度以及超时时的处理方式。持续时间可以较短（10 分钟）或较长（24 小时或更久）。在此期间可能会多次调用 /challenge/await API。两次调用 /challenge/await 之间的最短间隔应为 5 秒。此外，/challenge/await 可能返回 HTTP 代码 429，并在 HTTP 响应中包含 Retry-After 头。游戏在进行 k-ID API 调用时应始终检查此头。

同意挑战的过期

同意挑战预计在 7 天后过期。

获取家长的电子邮件地址

如果授予了同意，并且 /challenge/await 的 status 字段返回值为 PASS，则家长的电子邮件地址将在 approverEmail 字段中返回。游戏可以存储该地址以用于未来的客户服务案例。

测试家长同意

可以在 API 中测试家长同意，而无需通过家庭门户的家长同意流程。为此，您可以调用 /test/set-challenge-status 来设置同意挑战的状态。您可以将状态分配为 PASS 或 FAIL。您还必须在请求体中传递 age 和 jurisdiction。可选地，您可以传递一个电子邮件地址，使其在 approverEmail 字段中返回。下一次使用相同 challengeId 调用 challenge/await 时，将返回您分配的信息。这使您能够快速测试游戏中的家长同意场景。