부모 동의 구하기

/age-gate/check의 status 필드에서 CHALLENGE 값이 반환되는 경우, 응답의 challengeId 필드에는 k-ID 엔진의 동의 도전 ID가 포함됩니다. 이제 플레이어가 부모 동의를 구할 수 있는 창을 표시해야 합니다.

동의 도전

동의 도전은 플레이어의 동의 요청을 나타냅니다. 동의 도전에 대한 추가 정보는 /age-gate/check API에서 반환됩니다.

/age-gate/check API는 부모가 https://k-id.com/code로 직접 이동하여 입력할 수 있는 일회성 비밀번호와 QR 코드로 렌더링할 수 있는 URL을 반환합니다. 동의 도전 창은 QR 코드와 일회성 비밀번호를 표시하고, 동의를 부여할 수 있는 부모나 보호자의 이메일 주소를 플레이어가 입력할 수 있는 입력 필드를 제공해야 합니다.

동의 도전 창을 표시한 후, 게임은 이제 도전이 성공적으로 완료될 때까지 기다려야 합니다. Challenge.StateChange 이벤트를 수신하는 웹훅을 활용하는 것이 강력히 권장됩니다. 대체 옵션으로, /age-gate/check 응답에서 반환된 도전 ID로 /challenge/get-status API를 주기적으로 호출하여 폴링을 사용할 수 있습니다. 부모는 가족 포털에서 동의 요청을 받았으며, 이메일 메시지, QR 코드를 사용하거나 창에 표시된 URL로 이동하여 코드를 제공하여 승인할 수 있습니다. 동의 요청은 전달된 timeout 매개변수 값 후에 만료되며, 최대 180초까지 가능합니다. 또한 0초의 timeout을 전달할 수 있으며, 이는 차단하지 않고 도전의 현재 상태를 반환합니다. 호출이 반환된 후 도전이 여전히 대기 중인 경우, 후속 호출에 대한 응답의 status 필드 값은 POLL_TIMEOUT이 됩니다. k-ID 부모 포털을 통해 동의가 부여된 경우 호출은 PASS 상태로 반환되고, 요청이 거부된 경우 FAIL로 반환됩니다.

QR 코드나 일회성 비밀번호가 부모나 보호자에 의해 k-ID 부모 포털에서 동의를 부여하는 데 사용된 경우, 게임 워크플로우에서 다른 작업을 수행할 필요가 없습니다. 플레이어에 의해 부모나 보호자의 이메일 주소가 제공된 경우, 게임은 이 이메일 주소를 /challenge/send-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/get-status?challengeId=%s"),
                *BaseUrl, *ChallengeId);

    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;

            // 경과 시간이 전체 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(""));
        }

    });
}

동의를 기다리는 동안 플레이어는 무엇을 할 수 있나요?

일부 게임의 경우 부모가 동의를 부여할 때까지 플레이어가 게임을 계속 진행하는 것을 완전히 중단하는 것이 적절하며, 창은 모달이어야 합니다. 다른 게임의 경우 미성년 플레이어가 부모 동의가 요청되는 동안 액세스가 거부되기 전에 일정 시간 동안 계속 진행하는 것이 합리적일 수 있습니다. 이 경우 부모 동의를 기다리는 동안 게임은 플레이어에 대한 데이터 수집을 피하거나 동의가 필요할 수 있는 다른 기능에 대한 액세스를 제공하는 책임이 있습니다.

대기 중인 동의 도전

/age-gate/check API에서 CHALLENGE 상태가 반환될 때, 도전이 활성화되어 있는 동안 반환된 도전 ID는 로컬 스토리지에 저장되어야 합니다. 게임이 시작될 때 활성 도전의 존재는 게임이 이전과 동일한 동의 도전 창을 다시 표시하도록 지시합니다. 로컬 스토리지에서 도전 ID를 검색한 후, /challenge/get API를 호출하여 일회성 비밀번호와 QR 코드 URL을 포함한 현재 도전에 대한 정보를 검색하고, 도전 창을 다시 사용자에게 표시해야 합니다.

부모 응답을 얼마나 오래 기다려야 하나요?

게임은 동의가 부여될 때까지 얼마나 오래 기다릴지와 그 시간이 만료되면 무엇을 할지 결정해야 합니다. 지속 시간의 선택은 짧을 수 있습니다(10분) 또는 더 길 수 있습니다(24시간 이상). 이 시간 동안 /challenge/get-status API에 대한 많은 호출이 이루어질 수 있습니다. /challenge/get-status 호출 사이에는 최소 5초의 지연이 있어야 합니다. 또한 /challenge/get-status는 HTTP 응답에 Retry-After 헤더와 함께 HTTP 코드 429를 반환할 수 있습니다. k-ID API 호출을 할 때 게임은 항상 이 헤더를 확인해야 합니다.

동의 도전 만료

동의 도전 자체는 만료되지 않지만, 생성된 시간 기반 인증 방법(예: OTP, 이메일 링크)은 만료됩니다. k-ID가 사용자 플로우 내에서 시간 기반 인증을 사용하는 방법에 대한 자세한 내용은 시간 기반 인증을 참조하세요.

부모 이메일 주소 가져오기

동의가 부여된 경우, 부모의 이메일 주소는 /challenge/get-status 응답의 approverEmail 필드에서 반환됩니다. 이는 향후 고객 서비스 사례에서 사용하기 위해 게임에서 저장할 수 있습니다.

부모 동의 테스트

가족 포털에서 부모 동의 플로우를 거치지 않고도 API에서 부모 동의를 테스트할 수 있습니다. 이를 위해 /test/set-challenge-status를 호출하여 동의 도전의 상태를 설정할 수 있습니다. 상태를 PASS 또는 FAIL로 할당할 수 있습니다. 또한 본문의 일부로 age와 jurisdiction를 전달해야 합니다. 선택적으로 approverEmail 필드에서 반환할 이메일을 전달할 수 있습니다. 동일한 challengeId를 사용한 challenge/get-status의 다음 호출은 할당한 정보를 반환합니다. 이를 통해 게임에서 부모 동의 시나리오를 빠르게 테스트할 수 있습니다.