Skip to main content
PlayFab Services SDK에는 플레이어의 세션을 활성 상태로 유지하는 데 도움이 되는 백그라운드 토큰 새로 고침 메커니즘이 포함되어 있습니다. 이 메커니즘의 작동 방식과 게임이 조치를 취해야 하는 시점을 이해하는 것은 중요하며, 특히 일시 중단 및 재개를 지원하는 Game Development Kit(GDK) 타이틀에서는 더욱 그렇습니다.

자동 토큰 새로 고침의 작동 방식

SDK는 플레이어의 엔터티 토큰을 주기적으로 확인하는 백그라운드 작업자를 실행합니다. 토큰이 여전히 유효하지만 만료가 임박한 경우(만료까지 1시간 이내), SDK는 원래 로그인 호출의 자격 증명을 사용해 자동으로 다시 인증합니다. 이 새로 고침이 성공하면 토큰이 투명하게 업데이트되고 PFEntityHandle은 계속 유효한 상태를 유지합니다. 게임에서 조치를 취할 필요가 없습니다. 이러한 자동 토큰 새로 고침은 PFEntityRegisterTokenRefreshedEventHandler 콜백을 등록하여 관찰할 수 있습니다(투명한 새로 고침 참조).

게임이 토큰 만료를 처리해야 하는 경우

SDK가 토큰을 자동으로 새로 고칠 수 없는 시나리오가 있습니다:
  • 토큰이 이미 만료된 경우. 자동 새로 고침은 토큰이 여전히 유효할 때만 작동합니다. 예를 들어 긴 일시 중단/재개 주기 후처럼 토큰이 완전히 만료된 경우 SDK는 자동 재로그인을 시도하지 않습니다. 대신 TokenExpiredHandler를 통해 게임에 알립니다.
  • 원래 로그인 자격 증명이 더 이상 유효하지 않은 경우. 로그인 요청에 원래 제공된 핸들이나 토큰이 더 이상 유효하지 않으면 자동 새로 고침이 실패하고 TokenExpiredHandler가 호출됩니다.
PFEntityTokenExpiredEventHandler를 등록하는 것은 모든 타이틀에 권장되며, 일시 중단 및 재개를 지원하는 GDK 타이틀에는 필수입니다. 이 핸들러가 없으면 만료된 토큰에서 복구할 방법이 없습니다.

TokenExpiredHandler 등록

콜백을 등록하려면 PFEntityRegisterTokenExpiredEventHandler를 사용하고, 토큰이 만료될 때 다시 인증하려면 PFAuthenticationReLoginWith*Async를 사용합니다.

GDK: 일시 중단, 재개, Quick Resume

GDK 플랫폼(XBOX 콘솔 및 GDK를 사용하는 Windows)에서는 예를 들어 플레이어가 다른 게임으로 전환한 후 Quick Resume을 통해 다시 돌아오는 경우처럼 게임이 오랜 기간 동안 일시 중단될 수 있습니다. 일시 중단 중에 엔터티 토큰이 만료될 수 있습니다. 일시 중단 중에는 코드가 실행되지 않으므로 SDK의 주기적인 백그라운드 새로 고침이 토큰을 살아 있게 유지할 수 없습니다.

재개 시 발생하는 일

게임이 재개되면 SDK는 즉시 재개된 상태를 감지하고 엔터티 토큰을 확인합니다. 다음 주기적인 새로 고침 주기를 기다리지 않습니다. 일시 중단 중에 토큰이 만료된 경우:
  1. SDK가 만료된 토큰을 감지합니다.
  2. TokenExpiredHandler 콜백이 호출됩니다.
  3. 게임은 새 토큰을 획득하기 위해 핸들러에서 PFAuthenticationReLoginWith*Async를 호출해야 합니다.
재개 시 토큰 확인은 네트워크 연결이 복원되는 즉시 트리거됩니다. 재개 후 네트워크를 다시 초기화하는 데 시간이 걸리면 SDK는 토큰을 확인하기 전에 연결을 기다립니다. 토큰 확인이 손실되지 않습니다.

투명한 새로 고침

SDK가 플레이어의 엔터티 토큰을 자동으로 새로 고칠 때 게임에서 이를 알고 싶다면 콜백을 등록할 수 있습니다. 이 핸들러는 SDK가 만료가 임박한 토큰을 성공적으로 새로 고칠 때 호출됩니다. 게임에서 조치를 취할 필요가 없습니다.

핸들러 등록 해제

PlayFab을 종료할 때 또는 토큰 만료 및 새로 고침 콜백 수신을 중지하려는 경우, 적절한 등록 해제 함수를 호출합니다.

참조

API 참조 문서
마지막 수정일 2026년 8월 25일