세션 및 권한

세션과 권한은 플레이어가 게임에서 액세스할 수 있는 기능과 기능을 결정하는 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를 사용하여 추가 권한을 요청합니다.

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

권한 업그레이드 위젯 사용

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

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

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

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

요청 예시

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

{
  "challengeId": "ae6d4729-af32-42ea-8ef2-ff46c7664802",
  "email": "parent@example.com"
}

요청 매개변수

속성	설명	필수?
challengeId	/session/upgrade에 의해 생성된 VPC Challenge의 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 업데이트를 받을 수 있습니다.

세션 웹훅

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

• Session.ChangePermissions: 부모가 권한을 수정할 때 전송
• Session.Delete: 세션이 삭제될 때 전송

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