Skip to main content

Seeking Parental Consent

In the case where the value CHALLENGE is returned in the status field of the /age-gate/check, the challengeId field in the response contains the ID of the Consent Challenge in the k-ID Engine. A window should now be shown that allows the player to seek parental consent.

The Consent Challenge represents the player's request for consent. Additional information about the Consent Challenge is returned from the /age-gate/check API.

The /age-gate/check API returns a one time password that can be entered by a parent by browsing directly to https://k-id.com/code and a URL that can be rendered as a QR Code. The consent challenge window should show the QR code and one time password, as well as an input field to allow the player to enter the email address of a parent or guardian who can grant consent.

Challenge

After showing the consent challenge window, the game should now invoke the /challenge/await API periodically with the challenge ID returned the the /age-gate/check response. The parent has received the request for consent in the Family Portal, and can approve from the email message, using the QR code, or entering the URL displayed on the window and providing the code. The request for consent will timeout after the value of the timeout parameter passed in, up to a maximum of 180 seconds. It is also possible to pass in a timeout of 0 seconds which will not block and will return the current status of the challenge. After the call returns, if the challenge is still pending, the value in the status field of the response for subsequent calls will be POLL_TIMEOUT. The call will return with a status of PASS if consent has been granted via the k-ID parent portal, and FAIL if the request was denied.

If the QR code or one time password is used by a parent or guardian to grant consent in the k-ID parent portal, then nothing else needs to be done in the game workflow. If an email address for a parent or guardian is provided by the player, then the game should pass this email address as a parameter to the /challenge/email API, which will send a pre-configured email to the address with a link that leads a parent to the Family Portal where they can approve. Configuration options for this email are provided in the Publisher Portal.

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(""));
        }

    });
}

For some games, it is appropriate to stop the player from continuing at all in the game until a parent grants consent, and the window should be modal. In other games, it might be reasonable that an underage player is allowed to continue for a certain amount of time before being denied access while parental consent is requested. In this case, while waiting for parental consent, the game is responsible to avoid collecting data about the player, or giving access to other functions that might require consent.

When a status of CHALLENGE is returned from /age-gate/check API, the returned challenge ID should be stored in local storage while the challenge is active. The presence of an active challenge when the game starts directs the game to return show the same consent challenge window from before. After retrieving the challenge ID from local storage, the /challenge/get API should be invoked to retrieve information about the current challenge, including the one time password and QR code URL, and the challenge window should again be displayed to the user.

How Long To Wait For A Parent Response​

The game must determine how long the to wait for consent to be granted and what to do if that time expires. The choice of duration could be short (10 minutes) or longer (24 hours or more). There may be many calls made to the /challenge/await API during this time. Between calls to /challenge/await, there should be a minimum of 5 seconds delay. Also, the /challenge/await can return HTTP code 429 with a Retry-After header in the HTTP response. The game should always check for this header when making k-ID API calls.

A Consent Challenge should be expected to expire after 7 days.

Getting the Parent Email Address​

If consent is granted, and /challenge/await returns with PASS in the status field, the email address of the parent is returned in the approverEmail field. This can be stored by the game for use in future customer service cases.

It is possible to test parental consent in the API without going through the parental consent flow in the Family Portal. To do this, you can call /test/set-challenge-status to set the status of the Consent Challenge. You can assign the status to PASS or FAIL. You must also pass the age and jurisdiction as part of the body. Optionally you can pass an email to return in the approverEmail field. The next call to challenge/await using the same challengeId will return the information you assigned. This allows you to rapidly test parental consent scenarios in your game.