본문으로 건너뛰기

챌린지

Consent Challenge는 아동이 게임이나 게임 기능에 대한 액세스 동의를 요청할 때 생성됩니다. 확인된 신뢰할 수 있는 성인이 동의 Challenge와 연결되면 Challenge가 k-ID Family Connect의 신뢰할 수 있는 성인에게 액세스 요청으로 표시됩니다.

Challenge란 무엇인가요?​

동의 Challenge는 플레이어의 부모 동의 요청을 나타냅니다. 플레이어의 연령이 현재 관할권에서 Verifiable Parental Consent (VPC)를 요구하는 경우 k-ID는 플레이어가 게임이나 기능에 액세스하기 전에 신뢰할 수 있는 성인이 승인해야 하는 Challenge를 생성합니다.

Challenge 생성​

Challenge는 다음 경우에 자동으로 생성됩니다:

  • 플레이어의 연령이 부모 동의를 요구하는 경우(/age-gate/check API에 의해 결정됨)
  • 플레이어가 보호자 동의가 필요한 권한에 대한 액세스를 요청하는 경우(/session/upgrade API를 통해)

Challenge ID는 API 응답에서 반환되며 게임에서 플레이어와 연결된 로컬 스토리지나 클라우드 스토리지에 저장해야 합니다.

Challenge 정보​

Challenge가 생성되면 API는 다음을 반환합니다:

  • challengeId: Challenge의 고유 식별자
  • oneTimePassword: 부모가 동의 포털에 액세스하기 위해 입력할 수 있는 비밀번호
  • url: 모바일 액세스를 쉽게 하기 위해 QR 코드로 렌더링할 수 있는 URL

동의 Challenge 창은 QR 코드, 일회용 비밀번호 및 플레이어가 동의를 부여할 수 있는 부모나 보호자의 이메일 주소를 입력할 수 있는 입력 필드를 표시해야 합니다.

Challenge

Challenge 상태​

동의 Challenge 창을 표시한 후 게임은 Challenge가 성공적으로 완료될 때까지 기다려야 합니다. Challenge.StateChange 이벤트를 수신하는 웹훅을 사용하는 것이 강력히 권장됩니다. 대체 옵션으로 Challenge ID로 /challenge/get-status API를 주기적으로 호출하여 폴링할 수 있습니다.

Challenge 상태는 다음일 수 있습니다:

  • PASS: 신뢰할 수 있는 성인이 동의를 부여함
  • FAIL: 요청이 거부됨
  • PENDING: Challenge가 여전히 응답을 기다리는 중
  • POLL_TIMEOUT: 폴링 타임아웃에 도달함(타임아웃이 있는 폴링 사용 시)

신뢰할 수 있는 성인에게 알림​

동의 Challenge에 대해 신뢰할 수 있는 성인에게 알리는 여러 방법이 있습니다:

QR 코드 및 일회용 비밀번호​

Challenge 응답에는 QR 코드로 렌더링할 수 있는 URL과 일회용 비밀번호가 포함됩니다. 부모는 두 방법 중 하나를 사용하여 동의 포털에 직접 액세스할 수 있습니다.

이메일 알림​

플레이어가 부모나 보호자의 이메일 주소를 제공하는 경우 게임은 이 이메일 주소를 /challenge/send-email API의 매개변수로 전달해야 하며, 이 API는 부모가 승인할 수 있는 Family Connect로 연결되는 링크가 포함된 사전 구성된 이메일을 주소로 보냅니다. 이 이메일에 대한 구성 옵션은 Compliance Studio에서 제공됩니다.

게임은 동의가 부여될 때까지 얼마나 기다릴지, 그리고 그 시간이 만료되면 어떻게 할지 결정해야 합니다. 기간 선택은 짧을 수 있거나(10분) 더 길 수 있습니다(24시간 이상).

이 시간 동안 /challenge/get-status API에 대한 많은 호출이 이루어질 수 있습니다. /challenge/get-status 호출 사이에는 최소 5초 지연이 있어야 합니다. 또한 /challenge/get-status는 HTTP 코드 429를 반환할 수 있습니다. 게임은 429 응답을 처리할 때 적절한 재시도 로직을 구현해야 합니다.

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

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

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

Challenge 만료 및 시간 기반 인증​

동의 Challenge 자체는 만료되지 않지만 생성된 시간 기반 인증 방법은 만료됩니다(예: OTP, 이메일 링크). k-ID는 사용성을 유지하면서 보안을 보장하기 위해 시간 기반 인증 메커니즘을 구현합니다.

일회용 비밀번호(OTP)​

각 Challenge는 부모가 동의 포털에 액세스하는 데 사용할 수 있는 고유한 OTP를 생성합니다. 이러한 OTP는:

  • Challenge가 생성될 때 자동으로 생성됨
  • 1시간 동안 유효함
  • /challenge/generate-otp API를 통해 새로고침됨

QR 코드 URL​

Challenge 응답에는 모바일 액세스를 쉽게 하기 위해 QR 코드로 렌더링할 수 있는 URL이 포함됩니다. 이 URL은:

  • 포함된 OTP 포함
  • OTP와 함께 만료됨(1시간)
  • 부모를 위한 원활한 모바일 경험 제공

Challenge 생성 엔드포인트(/age-gate/check, /session/upgrade 등)에서 반환되는 Challenge URL과 /challenge/send-email에서 보내는 링크는 동일한 암호화 서명된 Challenge JWT를 공유합니다. JWT의 exp 클레임이 링크의 유효 기간을 결정합니다:

  • 라이브 모드: Challenge URL은 생성 후 2주 후에 만료됩니다.
  • 테스트 모드: Challenge URL은 생성 후 7분 후에 만료됩니다. 짧은 수명은 2주를 기다리지 않고 만료된 URL 처리를 테스트할 수 있도록 의도된 것입니다. 테스트 모드에 대한 자세한 내용은 Testing을 참조하세요.

이전에 생성된 URL을 열지 않고도 여전히 사용 가능한지 확인하려면 JWT를 디코딩하고 표준 exp 클레임을 확인하세요. Challenge 자체는 만료되지 않으므로(Challenge는 만료되지 않습니다 참조), 링크가 만료되어도 새 Challenge를 생성할 필요가 없습니다. 대신 액세스 방법을 새로 고치세요:

  • 동일한 challengeId로 /challenge/get을 호출하여 활성 Challenge의 새 URL과 OTP를 가져옵니다.
  • 이메일 링크를 다시 보내려면 /challenge/send-email을 다시 호출합니다.

모범 사례​

k-ID의 시간 기반 인증을 구현할 때:

  1. 반응적으로가 아닌 사전에 만료 모니터링
  2. 자격 증명이 만료될 때 우아한 성능 저하 구현
  3. 타임아웃 상태에 대한 명확한 사용자 피드백 제공
  4. 테스트 환경에서 타임아웃 시나리오 철저히 테스트
  5. 새로고침 작업 중 네트워크 중단과 같은 엣지 케이스 계획

신뢰할 수 있는 성인 이메일 주소 가져오기​

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

Challenge 테스트​

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