| 도움말 |
|---|
게임에서 초기화 및 상태 변화 이벤트(foreground<->background)를 연동하는 방법을 안내합니다. |
| 하위 페이지(하위 항목 표시) |
|---|
App 상태 변화 이벤트 정의
게임 app이 실행되어 종료될 동안 여러가지의 상태 변화가 발생할 수 있습니다.
게임 app의 실행 도중 홈버튼을 이용하여 앱이 백그라운드로 이동할 수 있고, 다시 게임 app 아이콘을 탭하여 포그라운드로 이동할 수 있습니다.
카카오 게임 SDK는 게임 app의 상태 변화(실행, 백그라운드 이동, 포그라운드 이동)에 따라 내부적으로 몇가지 동작을 수행합니다.
백그라운드로 이동할때, 배터리 소모를 막기 위해 플랫폼 서버로 주기적으로 발송하는 Heartbeat을 중단하는 작업을 한다거나, 포그라운드로 올라올때, 인증 토큰이 계속 유효한지 검사하는 등의 작업을 수행합니다.
게임의 상태 변화를 처리하기 위해 호출해야 하는 카카오게임 SDK의 API는 다음과 같습니다.
...
게임 app의 상태 변화
...
카카오게임 SDK API
...
게임 실행
...
Start
...
백그라운드 이동
...
Pause
...
포그라운드 이동
...
Resume
게임 실행 (Start)
게임이 실행되면 SDK는 게임에 의해 호출되는 Start API를 통해 SDK 초기화 및 "Start" 상태 변화 동작을 수행합니다.
"Start"는 게임 클라이언트 버전을 비롯한 몇가지 설정 정보들에 기반하여 게임 실행에 필요한 기본적인 정보들을 서버로부터 전달받고,
"긴급 공지", "점검 안내", "게임 클라이언트 업데이트 안내", "이용 약관 안내", "자동 로그인"의 동작을 순차적으로 수행합니다. 물론 이 중 "자동 로그인"은 이미 로그인을 한 기록이 있는 사용자에 한해 수행됩니다.
이 일련의 절차가 끝나면 Start API 호출 시 게임에서 입력한 콜백 함수를 통해 게임에 "Start"의 결과를 전달하는데, 이 때 전달되는 "Start"의 결과는 인증 여부와는 무관합니다.
즉, 자동로그인이 어떤 이유에 의해 실패했다 할지라도 그 이전에 수행된 일련의 과정들이 성공적으로 수행되었다면 성공을 전달하며 인증 여부에 대한 정보는 별도의 변수를 통해 함께 전달합니다.
따라서, 게임은 Start API의 결과로 전달된 결과가 실패였다면 게임을 실행할 수 없다는 상황으로 간주하여 Start API호출을 재시도하거나 혹은 게임을 종료시키는 동작을 수행해야 합니다.
Start API의 결과가 성공이라면 함께 전달된 인증 여부 정보에 따라 게임의 메인 씬으로 이동할 지 로그인 씬으로 이동할 지를 결정할 수 있습니다.
백그라운드 이동 (Pause)
게임이 백그라운드로 이동하게 될 때 게임이 SDK의 Pause API 를 호출하여 "Pause" 상태 변화 동작을 수행합니다.
"Pause"는 플랫폼 서버와의 연결된 세션을 종료함으로써 네트워크 사용량을 최소화하며 배터리 소모를 방지합니다.
포그라운드 이동 (Resume)
...
Definition of App Status Change Event
The status can change many times while a game app is running.
While a game app is running, the user may tap the Home button to run the app in the background, then tap the game app icon again to move it to the foreground.
The Kakao Game SDK internally performs several actions according to the change in game app status (running, moved to background, or moved to foreground).
When the app moves to the background, the SDK stops sending Heartbeat signals to the platform server to prevent battery drain. When the app moves to the foreground, it performs tasks such as checking if the authentication token is still valid.
The following APIs of the Kakao Game SDK must be called to process game status change:
Game App Status Change | Kakao Game SDK API |
|---|---|
Game Start | Start |
Move to background | Pause |
Move to foreground | Resume |
Game Start (Start)
When a game is started, the SDK performs SDK initialization and "Start" status change through the Start API called by the game.
“Start” receives the basic information needed to start a game from the server based on some settings including game client version and then performs the actions of “Urgent announcement”, “Guide of testing”, “Guide of game client update”, “Guide of User’s Agreement” and “Automatic login” sequentially. Of course, “Automatic login” is performed only for users with a previous login record.
After this series of actions, the result of “Start” is sent to the game through the callback function inputted in the game when the Start API was called. The result of “Start” that is sent at this time is not related to authentication. In other words, a success is delivered even if automatic login had failed for some reason if the series of previous processes were successfully executed. The result of authentication is sent at the same time through a separate parameter.
Therefore, the game must regard a failure delivered by the Start API as a note that it is in a situation in which it cannot run, and try to call the Start API again or terminate the game. If the result of the Start API is a success, the game can decide whether to move to the main scene or to the login scene depending on the result of authentication sent at the same time.
Move to Background (Pause)
When the game is moved to the background, it calls the Pause API of the SDK to change the status to “Pause.”
"Pause" terminates the session connected to the platform server to prevent wasting the battery by minimizing network utilization.
Move to Foreground (Resume)
To move back to the foreground from the background, the game calls the Resume API of the SDK to change the status to “Resume.”
"Resume" restores the terminated session connection and performs a series of actions to maintain the authentication status.
If the server connection fails or the authentication details have expired, “Resume” delivers the failure through the callback function sent when the was API called. The game must retry “Resume” or move to the login scene to authenticate again depending on the cause of the failure indicated by the error code.