본문으로 건너뛰기

챌린지

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

Challenge 생성​

부모 동의가 필요한 생년월일로 /age-gate/check를 호출할 때 Challenge가 자동으로 생성됩니다. Challenge 정보는 응답에서 반환됩니다:

{
  "status": "CHALLENGE",
  "challenge": {
    "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
    "oneTimePassword": "ABC123",
    "type": "CHALLENGE_PARENTAL_CONSENT",
    "url": "https://family.k-id.com/authorize?otp=ABC123"
  }
}

Challenge 정보​

Challenge가 생성되면 다음을 받습니다:

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

Challenge 표시​

Challenge를 표시하는 방법과 표시할 정보에 대한 정보는 핵심 개념 섹션의 Challenge를 참조하세요.

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

동의 Challenge에 대해 신뢰할 수 있는 성인에게 알리는 여러 방법이 있습니다. 알림 방법에 대한 자세한 내용은 핵심 개념 섹션의 Challenge를 참조하세요.

이메일 알림​

플레이어가 부모나 보호자의 이메일 주소를 제공하는 경우 Challenge ID와 이메일 주소로 /challenge/send-email를 호출합니다:

POST /api/v1/challenge/send-email
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "challengeId": "683409f1-2930-4132-89ad-827462eed9af",
  "email": "parent@example.com"
}

또는 이메일 주소를 지정하지 않고 /challenge/send-email를 호출할 수 있으며, API는 플레이어에 대한 권한을 가장 최근에 승인한 신뢰할 수 있는 성인에게 이메일을 보냅니다. 연결된 이메일 주소를 찾을 수 없는 경우 API는 INVALID_EMAIL 오류 코드로 응답합니다.

Challenge 상태 확인​

동의 Challenge를 표시한 후 신뢰할 수 있는 성인이 동의 프로세스를 완료할 때까지 기다립니다. Challenge 상태를 두 가지 방법으로 확인할 수 있습니다:

웹훅(권장)​

웹훅 이벤트 구조에 대한 자세한 내용은 Challenge.StateChange를 참조하세요.

Challenge.StateChange 이벤트를 받을 웹훅 엔드포인트를 구성합니다. 자세한 내용은 웹훅을 참조하세요.

폴링​

Challenge ID로 /challenge/get-status API를 주기적으로 폴링합니다:

GET /api/v1/challenge/get-status?challengeId=683409f1-2930-4132-89ad-827462eed9af
Authorization: Bearer your-api-key

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

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

PASS 응답 예시​

{
  "status": "PASS",
  "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
  "approverEmail": "parent@example.com"
}

동의 대기​

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

동의 대기 및 대기 시간에 대한 자세한 내용은 핵심 개념 섹션의 Challenge를 참조하세요.

대기 중인 동의 Challenge​

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

자세한 내용은 핵심 개념 섹션의 Challenge를 참조하세요.

Challenge 만료​

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

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

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

Challenge에 대한 자세한 내용(테스트 Challenge 포함)은 핵심 개념 섹션의 Challenge를 참조하세요.