본문으로 건너뛰기

세션

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

세션이란 무엇인가요?​

k-ID Session은 특정 관할권에 대한 게임에서 플레이어의 권한을 설명하는 장기 객체입니다. 연령에 관계없이 모든 플레이어는 게임에 액세스하는 데 필요한 장기 k-ID Session을 받습니다. 세션에는 플레이어가 게임을 플레이하는 관할권에서의 권한이 포함됩니다.

아동이나 청소년의 경우 세션은 신뢰할 수 있는 성인이 권한을 추가하거나 제거하거나 생일로 인해 연령이 변경되어 수정될 수 있습니다. 세션은 일반적으로 게임에서 로컬 또는 클라우드 스토리지에 캐시됩니다. 게임이 플레이어 계정을 구현하는 경우 세션은 게임에서 플레이어의 신원과 연결될 수도 있습니다.

세션 수명 주기​

k-ID Session은 자동으로 만료되지 않습니다. 플레이어와 연결된 로컬 또는 클라우드 스토리지에 캐시되도록 설계되었습니다. 아동 및 청소년의 경우 세션은 부모가 Family Connect를 사용하여 권한을 추가하거나 제거하거나, 플레이어가 생일을 맞아 세션이 설정된 관할권에서 새로운 연령 카테고리로 "연령 상승"하는 경우 변경될 수 있습니다.

신뢰할 수 있는 성인에 의해 액세스가 부여된 후 플레이어는 프로덕트당 정확히 하나의 세션을 가집니다. 권한이 변경되는 경우(부모 수정, 연령 상승 이벤트 또는 권한 업그레이드를 통해) 동일한 세션 ID가 새로운 권한으로 업데이트됩니다. 새로운 세션이 생성되지 않습니다. 기존 세션이 플레이어의 액세스 현재 상태를 반영합니다. 그러나 세션이 취소되고 신뢰할 수 있는 성인이 동의 흐름을 다시 완료하는 경우 새로운 세션 ID를 가진 새로운 세션이 생성됩니다.

Session은 캐시되도록 설계되었으므로 게임이 시작될 때마다 /session/get API를 사용하여 새로고침하여 변경 사항을 가져와야 합니다.

세션 구조​

세션에는 다음이 포함됩니다:

  • sessionId: 세션의 고유 식별자
  • jurisdiction: 세션이 생성된 관할권
  • dateOfBirth: 플레이어의 생년월일(수집된 경우)
  • ageStatus: 플레이어의 연령 상태(DIGITAL_MINOR, DIGITAL_YOUTH 또는 LEGAL_ADULT)
  • permissions: 활성화/비활성화 상태가 있는 권한 배열
  • kuid: k-ID 사용자 ID(플레이어가 VPC를 거친 경우)
  • status: 세션 상태(항상 ACTIVE)
  • etag: 캐시 검증을 위한 엔티티 태그

세션 예시:

{
  "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"
      }
    ],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

세션 가져오기​

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

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

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

세션 캐싱​

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

게임이 재시작될 때마다 /session/get API에서 세션을 새로고침하는 것이 권장되지만 명시적으로 요구되지는 않습니다. 또한 k-ID 웹훅을 사용하여 /session/get API를 호출하는 대신 Session 업데이트를 받을 수 있습니다. k-ID API에 문제가 있는 경우 새로고침을 나중까지 연기할 수도 있습니다. 캐시된 세션은 문제가 해결되는 동안 k-ID API에 연결하지 않고 권한을 관리하는 데 사용할 수 있습니다.

세션 및 플레이어 신원​

k-ID Session은 플레이어 ID와 강하게 연결된 것으로 생각할 수 있습니다. 게임이 ID 시스템을 사용하는 경우 Session 자체는 플레이어 계정과 연결된 스토리지와 함께 JSON 문서로 완전히 저장될 수 있습니다.

기기 간 세션​

로컬 스토리지에 Session 객체를 캐싱할 때 동일한 플레이어에 대해 여러 기기의 로컬 스토리지에 다른 세션이 존재할 수 있습니다. 플레이어가 새 기기에서 게임을 플레이하는 경우 연령 게이트가 플레이어에게 표시되며, 이전에 필요했다면 다시 동의를 구해야 합니다.

한 번 이상 동의를 요청하지 않도록 하려면 k-ID 세션을 플레이어 계정과 연결된 클라우드 스토리지에 저장하고 플레이어가 어떤 기기에서든 로그인할 때마다 검색할 수 있습니다. 이 경우 기기 간에도 플레이어당 하나의 Session만 있습니다.

세션 웹훅​

Compliance Studio에서 k-ID의 이벤트를 받을 웹훅을 등록할 수 있습니다. 이를 통해 플레이어가 _연령 상승_할 때를 제외하고 k-ID 세션의 드문 변경 사항을 검색하기 위해 /session/get을 호출할 필요가 없습니다.

다음 웹훅 이벤트는 세션과 관련이 있습니다:

연령 상승 변경 사항은 웹훅을 트리거하지 않습니다

플레이어가 연령 상승하고 권한이 변경되는 경우(예: 권한이 플레이어 관리로 변경됨) k-ID는 웹훅 알림을 보내지 않습니다. 이러한 변경 사항을 감지하려면 세션 비교를 사용해야 합니다. 구현 가이드는 세션 및 권한 관리를 참조하세요.

세션 삭제​

부모가 Family Connect를 통해 프로덕트에 대한 액세스를 취소하면 세션이 삭제됩니다. /session/get을 사용하여 삭제된 세션을 쿼리할 때 API는 HTTP 400과 오류 코드 NOT_FOUND를 반환합니다. 삭제된 세션은 API에서 반환되지 않습니다. 세션이 존재하지 않았던 것처럼 나타납니다. 이것은 의도적인 것입니다. 세션이 삭제되면 세션이 더 이상 존재하지 않는 것처럼 처리해야 합니다.

통합에서 세션 삭제하기​

통합에서 /session/delete를 사용하여 세션을 직접 삭제할 수도 있습니다. 기본적으로 이는 소프트 삭제입니다. 세션은 취소되고 더 이상 조회할 수 없게 되지만, 레코드 자체는 보존됩니다. hardDelete: true를 설정하면 대신 세션과 여기에 포함된 동의가 영구적으로 삭제됩니다. 이 작업은 취소할 수 없으며, 하드 삭제가 명시적으로 활성화된 개발자만 사용할 수 있습니다. 기본 삭제의 강력한 버전이 아니라 실제 삭제 요청(예: 규제상의 삭제 요청)을 처리하는 데 사용하세요.

세션의 프로덕트가 다른 프로덕트가 의존하는 필수 프로덕트로 구성된 경우, 해당 세션을 삭제하면 의존하는 프로덕트의 세션이 의존하던 동의 기반을 잃을 수 있습니다. 선택적 essentialDependencies 필드를 사용하면 소프트 삭제와 하드 삭제 두 경로 모두에서 대신 어떤 동작을 할지 제어할 수 있습니다:

  • **ignore(또는 필드 생략)**는 지정된 세션만 삭제하며, 엔드포인트의 기존 동작과 정확히 동일합니다. 필드를 생략하면 기존 동작이 유지되며, 앞으로도 항상 그렇습니다.
  • **block**은 플레이어가 이 프로덕트에 의존하는 활성 프로덕트를 아직 보유하고 있는 동안 ESSENTIAL_DEPENDENTS_EXIST로 삭제를 거부하고, 의존 프로덕트 ID를 명시합니다. 의존 프로덕트가 고립되지 않도록 API가 보호해 주기를 원할 때 사용하세요.
  • **cascade**는 의존하는 세션을 먼저 삭제하고(각 세션마다 자체 Session.Delete 웹훅이 발송됩니다), 그다음 지정된 세션을 삭제합니다. 지정하지 않은 세션을 삭제하기 때문에 명시적으로 활성화된 개발자만 사용할 수 있으며, 클라이언트 액세스 토큰이 아닌 서버 측 API 키가 필요합니다.

활성 상태인 의존 프로덕트만 대상이 됩니다(세션이 이미 취소된 의존 프로덕트는 삭제를 차단하지 않습니다). 또한 개발자 계정을 넘나드는 의존성은 캐스케이드되지 않고 거부됩니다.

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