본문으로 건너뛰기

세션 및 권한

세션과 권한은 플레이어가 게임에서 액세스할 수 있는 기능과 기능을 결정하는 k-ID의 핵심 개념입니다.

세션​

k-ID Session은 현재 플레이어 및 위치에 대한 권한 및 연령 상태의 컬렉션을 포함합니다. 모든 플레이어는 활성 Session이 필요합니다. 게임은 활성 Session을 참조하여 게임에서 기능이 허용되거나 금지되는지 결정해야 합니다.

세션에 대한 자세한 내용은 세션을 참조하세요.

세션 가져오기​

세션을 두 가지 방법으로 검색할 수 있습니다:

  • /session/get: sessionId 또는 kuid로 세션 가져오기
  • /age-gate/check: 연령 게이트 흐름의 일부로 세션 생성 또는 업데이트

요청 예시​

GET /api/v1/session/get?sessionId=608616da-4fd2-4742-82bf-ec1d4ffd8187&etag=6d9d24fccd428f845b355122799948dd0a52fc5d
Authorization: Bearer your-api-key

/session/get API는 etag 매개변수를 사용하여 조건부 요청을 지원합니다. 마지막 요청 이후 세션이 변경되지 않은 경우 API는 HTTP 304(수정되지 않음)를 반환하여 불필요한 데이터 전송을 방지할 수 있습니다.

응답 예시​

{
  "session": {
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "etag": "6d9d24fccd428f845b355122799948dd0a52fc5d",
    "jurisdiction": "US-CA",
    "kuid": "123456",
    "permissions": [
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "ai-generated-avatars"
      },
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "text-chat-private"
      }
    ],
    "allowances": [],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

권한​

권한은 부모 동의가 필요하거나 연령 제한이 있을 수 있는 게임의 기능이나 기능을 나타냅니다. 각 권한은 다음을 기반으로 플레이어에 대해 허용되거나 금지될 수 있습니다:

  • 연령 및 관할권
  • 부모 동의(필요한 경우)
  • Compliance Studio의 권한 구성

권한에 대한 자세한 내용은 권한을 참조하세요.

권한 사용​

게임 코드는 각 k-ID 권한을 사용하여 게임에서 해당 기능에 대한 액세스를 제어해야 합니다. 권한의 enabled 필드가 true인 경우 게임에서 플레이어에 대해 기능을 활성화할 수 있음을 의미합니다. enabled 필드가 false인 경우 기능을 꺼야 합니다.

managedBy 필드는 이 권한을 허용하거나 금지할 수 있는 사람을 나타냅니다:

  • PLAYER: 플레이어가 이 권한을 직접 활성화/비활성화할 수 있음
  • GUARDIAN: 신뢰할 수 있는 성인만 이 권한을 활성화/비활성화할 수 있음
  • PROHIBITED: 현재 위치에서 현재 플레이어에 대해 이 권한이 절대 허용되지 않음

신뢰할 수 있는 성인의 동의와 관계없이 현재 위치에서 현재 플레이어에 대해 기능이 절대 허용되지 않는 경우 managedBy 필드에 값 PROHIBITED가 포함됩니다. 이 경우 게임은 기능을 꺼진 상태로 표시하는 대신 사용자 경험에서 금지된 기능을 완전히 제거하는 것이 적절합니다.

권한 업그레이드​

플레이어가 권한이 있는 세션을 받은 후 추가 권한을 허용하고 싶을 수 있습니다. /session/upgrade API를 사용하여 추가 권한을 요청합니다.

자세한 내용은 권한 업그레이드를 참조하세요.

법적 문서 및 데이터 고지 제시​

/session/upgrade는 업데이트된 법적 문서와 데이터 고지를 제시하여 신뢰할 수 있는 성인이 동일한 동의 시점에 검토하고 수락하도록 할 수 있습니다. 제시할 문서는 요청의 materialChange에 전달합니다.

  • materialChange.termsOfServiceDocument, materialChange.privacyPolicyDocument, materialChange.additionalLegalLinks: 제시할 법적 문서 변형의 구성된 ID.

다음 중 하나라도 요청되면 문서를 검토하고 수락할 수 있도록 챌린지가 생성됩니다.

  • 부모 동의가 필요한 보호자 관리 권한,
  • materialChange의 하나 이상의 법적 문서, 또는
  • 중요한 변경에 따른 재동의(아래 참조).

이 중 어느 것도 해당하지 않으면 이전과 동일하게 챌린지 없이 권한이 직접 부여됩니다. 세션에 아직 동의가 필요한 데이터 고지는 자동으로 포함되며, 챌린지를 수락하면 법적 문서와 데이터 고지 모두에 대한 동의가 기록됩니다.

신뢰할 수 있는 성인은 승인 페이지에서 실제 문서를 검토합니다. 해결된 문서를 읽으려면 업그레이드 응답의 challenge.documents 배열을 사용합니다. 각 항목에는 변형의 id, 지역화된 name, 법적 문서의 경우 url, 그리고 isDataNotice(이름만 있는 데이터 고지의 경우 true이며, 데이터 고지에는 url이 없음)가 포함됩니다. 재동의 체인(priorChallengeId)에서는 이 배열에 이전 챌린지의 문서가 누적되므로, 헤드 챌린지가 항상 전체 세트를 보유합니다.

기한이 있는 재동의 요청(중요한 변경)​

문서가 변경되어 신뢰할 수 있는 성인이 기한까지 다시 수락해야 하는 경우, 업그레이드 요청의 materialChange에 acceptanceDeadline을 추가합니다.

  • materialChange.acceptanceDeadline: 성인이 수락해야 하는 기한(RFC 3339 UTC 날짜/시간). 선택 사항: 생략하면 기한 없이 문서를 제시합니다. 설정하는 경우 미래 시점이어야 합니다.
  • materialChange.locale: 재동의 이메일의 로케일(기본값은 en).

기한을 설정하면 업그레이드가 능동적이고 기한이 있는 재동의가 됩니다. 챌린지에 기한이 포함되며(/challenge/get-status에서 expiresAt로 반환됨), 신뢰할 수 있는 성인에게 동일한 승인 페이지 링크가 이메일로 전송됩니다. 기한을 설정하지 않아도 문서는 승인 페이지에서 검토를 위해 제시되지만, 수락 기한은 적용되지 않습니다.

능동적 재동의와 수동적 재동의

acceptanceDeadline이 포함된 /session/upgrade의 materialChange는 업그레이드에 번들로 제공되는 능동적 재동의를 위한 것입니다. 액세스를 제한하지 않고 알림 전용(수동적) 이메일을 보내려면 전용 /session/send-material-change-notice API를 사용하세요.

권한 업그레이드 위젯 사용​

k-ID API를 사용하여 사용자 정의 VPC 흐름을 구축할 때 권한 업그레이드 위젯을 사용하여 플레이어가 부모 동의가 필요한 추가 권한을 요청할 수 있도록 할 수 있습니다. 위젯은 권한 업그레이드에 대한 동의 워크플로를 처리합니다.

보호자 관리 세션만

권한 업그레이드 위젯은 보호자 관리 세션에서만 작동합니다. 플레이어의 세션이 플레이어 관리(managedBy가 "PLAYER")인 경우, 챌린지를 생성하지 않고 /session/upgrade API를 직접 사용하여 권한을 활성화할 수 있으므로 위젯이 필요하지 않습니다.

부모 인증 필요

세션 권한 관리 위젯은 부모가 인증된 세션에서만 호스팅해야 합니다. 위젯은 자체 부모 인증을 제공하지 않으므로 미성년자에게 직접 제시해서는 안 됩니다. 위젯이 인증된 부모 또는 신뢰할 수 있는 성인에게만 표시되도록 항상 확인하세요.

필요한 경우와 작동 방식을 포함하여 권한 업그레이드에 대한 일반 정보는 핵심 개념 섹션의 권한 업그레이드를 참조하세요.

권한 업그레이드 위젯 URL 생성​

/widget/generate-manage-session-permissions-url API를 호출하여 권한 업그레이드 위젯 URL을 만듭니다. 이것은 신뢰할 수 있는 성인이 추가 권한을 검토하고 승인할 수 있는 고유 URL을 반환합니다.

요청 예시​

POST /api/v1/widget/generate-manage-session-permissions-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "email": "parent@example.com"
}

요청 매개변수​

속성설명필수?
sessionId세션의 ID예
email신뢰할 수 있는 성인의 이메일 주소예

응답 예시​

{
  "url": "https://family.k-id.com/widget?token=eyJhbGciOiJFUzM4NCIs..."
}

위젯 포함​

반환된 URL을 사용하여 웹사이트나 앱에 iframe을 만듭니다. 신뢰할 수 있는 성인은 이 인터페이스를 통해 추가 권한을 검토하고 승인할 수 있습니다:

<iframe 
  src="WIDGET_URL" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

업그레이드 결과 받기​

권한 업그레이드는 세션의 일부로 추적됩니다. 추가 권한이 승인되면 세션이 새 권한으로 업데이트됩니다. /session/get API를 호출하여 세션에서 업데이트된 권한을 확인할 수 있습니다.

실시간 업데이트를 위해 세션 관련 이벤트도 수신할 수 있습니다:

JavaScript 이벤트(클라이언트 측)​

이벤트 구조에 대한 자세한 내용은 Widget.ExitReview를 참조하세요.

권한 업그레이드 위젯이 iframe에 포함된 경우 위젯의 창 메시지를 수신할 수 있습니다:

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // 위젯 완료 이벤트 처리
  if (message.eventType === 'Widget.ExitReview') {
    // 권한 업그레이드 흐름 완료
    console.log('Permissions upgrade completed');
    handleUpgradeCompleted();
  }
});

웹훅(서버 측)​

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

세션 관련 이벤트를 받을 웹훅 엔드포인트를 구성합니다. 권한이 업그레이드되면 세션 변경 사항이 Session.ChangePermissions 이벤트에 반영됩니다. 자세한 내용은 웹훅을 참조하세요.

권한 업그레이드 및 세션​

위젯을 통해 권한이 업그레이드되면 세션이 새 권한으로 업데이트됩니다. 세션은 어떤 권한이 활성화되었는지와 활성화된 시기를 추적합니다. /session/get API를 호출하여 세션을 검색하여 업데이트된 권한을 확인할 수 있습니다.

권한 업그레이드가 세션과 함께 작동하는 방식에 대한 자세한 내용은 핵심 개념 섹션의 권한 업그레이드를 참조하세요.

세션 캐싱​

Session은 로컬 또는 클라우드 스토리지에 캐시되어야 하며 플레이어의 계정과 연결될 수 있습니다. k-ID 세션은 부모가 권한을 업데이트하거나 아동이나 청소년이 다음 연령 카테고리로 "연령 상승"하거나 부모나 플레이어가 삭제할 때만 변경됩니다.

게임이 재시작될 때마다 /session/get API에서 세션을 새로고침하는 것이 권장되지만 명시적으로 요구되지는 않습니다. 또한 k-ID 웹훅을 사용하여 /session/get API를 호출하는 대신 Session 업데이트를 받을 수 있습니다.

세션 웹훅​

세션 관련 이벤트를 받을 웹훅을 구성합니다:

자세한 내용은 웹훅을 참조하세요.