- Cập nhật lần cuối
Maintenance/Update
Understanding
Using the maintenance/update feature provided by the STOVE SDK, you can set or clear game-server maintenance and control updates by managing the game version.
The STOVE SDK runs inside the user's app (client). When the app launches, if maintenance is in progress or a new update is available, it shows a guidance popup to the user.
However, beyond STOVE's features, there are parts the game server must manage directly, so they need to be implemented together.
The SDK checks maintenance/update only at app launch
ㅁ The check happens only once at app launch (initialize); it isn't detected in real time during play.
ㅁ Maintenance detection during play (Heartbeat) and kicking connected users must be implemented by the game server directly.
Feature Providers
The maintenance/update feature is provided with roles split between STOVE (SDK) and the game (CP company).
| Feature | Provider | Configuration location |
|---|---|---|
| Determines maintenance status at SDK initialize and shows the popup | SDK (STOVE) | Partners |
| Determines platform-whitelist status and blocks access | SDK (STOVE) | Partners |
| Determines app-update status and shows the popup | SDK (STOVE) | Partners |
| Determines game-resource (CDN) update status | Game (CP company) | Game ops tool |
| Determines game-server maintenance status and manages the whitelist | Game (CP company) | Game ops tool |
| Kicks users and shows the game-maintenance popup | Game (CP company) | Game ops tool |
On PC, the STOVE PC Client handles maintenance/update notices automatically
For games launched via the STOVE PC Client, the client shows maintenance and app-update notices automatically, so the SDK-popup integration above mainly applies to mobile. Game-server-based maintenance, kick, and resource updates must be implemented regardless of platform.
Cautions for Maintenance on the Mobile Platform
- Due to the nature of the mobile platform, various exceptional situations can arise for users during maintenance.
- When the user is in a section with no server communication at the time of maintenance setup / user kick (e.g., lobby screen, during single-player)
- When the app was sent to the background before maintenance started — situations like app in background before maintenance → app to foreground during maintenance can occur.
- When the user is in a section where the network is physically cut off (e.g., airplane mode, subway)
- If server-based maintenance/update features are absent or not handled, the following problems can occur.
- Some users who weren't kicked access/play the game during maintenance
- Because resource updates are checked only at app launch, some users don't receive resource updates
- To prevent the problems above, the game server must implement the following items.
- Game-server maintenance setup (entry blocking)
- Server-based user-kick implementation
- App-update version / update options
- Resource-update version / update options
Integration Guide
Prerequisites
| Item | Details |
|---|---|
| Partners maintenance setup | Service maintenance and update management must be configured in Partners. |
| Game-server maintenance implementation | You must implement game-server maintenance setup (entry blocking), user kick, and app/resource update-version management. |
Basic Integration Structure
At STOVE SDK initialization (initialize), it checks maintenance/update status and automatically shows a context-appropriate guidance popup. The popup STOVE provides is a simple user-notice popup; in-game maintenance notices, user kick, input blocking, and server-level maintenance must be implemented separately by the game.
Be careful when implementing maintenance/update
The SDK provides minimal maintenance/update information only at the first app launch (initialize), so the subsequent flow must be controlled by the game server.
Maintenance & Update Flow
This is the full sequence in which the STOVE SDK and the game server judge maintenance/update in order when a user enters the game.
The earlier steps (①–⑤) are handled by the STOVE SDK at the platform level, and the later steps (⑥–⑨) by the game server at the game level.
| Order | Action detail | Provider |
|---|---|---|
| ① | At SDK initialize, calls the STOVE backend service to determine maintenance status. Maintenance status is returned only at the first app launch. | SDK (STOVE) |
| ② | Determines platform-whitelist status. (The platform whitelist is registered in Partners) | SDK (STOVE) |
| ③ | If not on the platform whitelist, shows the SDK maintenance popup / blocks access. | SDK (STOVE) |
| ④ | At SDK initialize, calls the STOVE backend service to determine app-update status. | SDK (STOVE) |
| ⑤ | If an app update exists, shows the SDK update popup. | SDK (STOVE) |
| ⑥ | Determines game-resource (CDN resource patch) update status. | Game (CP company) |
| ⑦ | Determines game-server maintenance status. | Game (CP company) |
| ⑧ | Determines game-server-whitelist status. (The game whitelist is registered in the game ops tool) | Game (CP company) |
| ⑨ | If not on the game-server whitelist, shows the game maintenance popup / blocks access. | Game (CP company) |
This breaks down how each situation is handled when maintenance or an update actually occurs within the full flow.
| Order | Action detail | Provider |
|---|---|---|
| ① | Partners maintenance setup (SDK maintenance setup). | Partners (STOVE) |
| ② | Game-server maintenance setup (server maintenance setup). | Game ops tool (CP company) |
| ③ | User kick. | Game ops tool (CP company) |
| ④ | Show the kick popup → handle app exit or restart. | Game (CP company) |
| ⑤ | When a user not handled at kick time accesses the game — if the game server is down (under maintenance): show an error popup → handle app exit or restart. |
Game (CP company) |
| ⑥ | When a user not handled at kick time accesses the game — if the game server is running (live verification): check game-server maintenance status → show the game maintenance popup → handle app exit or restart. |
Game (CP company) |
This is the flow when an app (client) or resource (CDN) update exists. It covers when a user who wasn't kicked accesses the game during an update check, or when only app/resource updates are applied without maintenance.
| Order | Action detail | Provider |
|---|---|---|
| ① | App-update (version-update) setup. | Partners (STOVE) |
| ② | Resource-update (resource-version-update) setup. | Game (CP company) |
| ③ | Communication occurs between a user (client) who hasn't received the update and the game server. | Game (CP company) |
| ④ | App-version comparison — if not the latest, go to step ⑤; if the latest, go to step ⑨. | Game (CP company) |
| ⑤ | Check whether the update is mandatory — if mandatory, go to step ⑥; if optional, also go to step ⑥ (however, if it's not a forced update, connected users are not kicked). |
Game (CP company) |
| ⑥ | Kick users to apply the mandatory update (not all users are kicked). | Game (CP company) |
| ⑦ | App restart → show the SDK app-update popup on the title screen → proceed with the app update. | Game (CP company) |
| ⑧ | Check whether a resource update exists — if it exists, go to step ⑨; if not, connect to the game. | Game (CP company) |
| ⑨ | Resource-version comparison — if not the latest, go to step ⑩; if the latest, connect to the game. | Game (CP company) |
| ⑩ | Check whether the update is mandatory — if mandatory, go to step ⑪; if optional, connect to the game (if it's not a forced update, connected users are not kicked). |
Game (CP company) |
| ⑪ | Kick users to apply the mandatory resource update (not all users are kicked). | Game (CP company) |
| ⑫ | App restart → show the resource-update popup on the title screen → download the resources → connect to the game after download completes. | Game (CP company) |
Development
SDK Integration
When maintenance or app-update status is detected in the result of SDK initialization (initialize), call OperationUI.handleResult to show the guidance UI the SDK provides and then control the subsequent game flow.
Prerequisites
- AuthUI module dependency:
OperationUIis included in the AuthUI module. Check that the AuthUI dependency is added to your project (Androidbuild.gradle, iOSPodfile/SPM, Unity/Unreal packages). - Partners configuration complete: configure service maintenance and update management in Partners in advance. The client receives this configuration in the
initializeresponse and branches the screen accordingly. - Call context:
handleResultneeds a live Activity (Android) /UIViewController(iOS) to show the screen. Confirm that the context hasn't been finished/dismissed at call time before calling. - Game-server-side implementation: SDK maintenance info is returned only at the first
initialize, so implement game-server entry blocking, user kick, and resource-version verification separately. (See Troubleshooting for details)
Development Flow
- Call
Auth.initialize(Android) /[SGSAuth initializeWithCompletionHandler:](iOS) /Auth.Initialize(Unity/Unreal) at game start. - Pass the
Result(including errorCode) received in the callback as-is toOperationUI.handleResult(activity, result) { ... }. OperationUIbranches onerrorCodeand automatically shows the appropriate screen.Auth.MaintenanceError(30003) → maintenance-notice screenAuth.AppUpdateError(30004) → app-update-notice screen (behavior branches by mandatory/optional option)- Other permission/account-related errors → the corresponding notice screen (sanction, dormancy, withdrawal, etc.)
- When the user interaction (confirm / go to update / exit app) finishes, the
listenercallback is called. Inside the callback, usehandled.isSuccessful()to continue the game-entry flow (login → character selection → lobby). - If
Auth.initializeitself fails for a reason other than maintenance/update (network error, etc.), implement retry logic separately.
Troubleshooting
Maintenance/update info is provided only at initialize
The SDK responds with maintenance/update status only at the first app launch (initialize). Since the SDK doesn't provide Heartbeat or real-time user kick, you must implement entry-blocking and kick logic separately on the game-server side. Use the SDK popup only for user notices, and take responsibility for forced-exit/restart handling on the game side.
| Error code / situation | Cause | Action |
|---|---|---|
Auth.MaintenanceError (30003) | Partners maintenance setting is active | Pass Result to OperationUI.handleResult to show the SDK maintenance screen. In the callback, don't let the user enter the game; exit the app or send them to a restart screen. |
Auth.AppUpdateError (30004) | A new version is set in Partners update management | Call OperationUI.handleResult → for a mandatory update, block user input (disable back, and on confirm, go to the store / exit the app). On the game server too, reject old-version access via client-version verification. |
Called OperationUI.handleResult but no screen appears | At call time the Activity was finished or the Fragment was detached | Right before calling, check !isFinishing && !isDestroyed on Android and that the viewController is alive as a presentedViewController on iOS. If using the Fragment version, call only when fragment.isAdded == true. |
| The maintenance popup is missing when returning from background to foreground | SDK maintenance info is returned only at initialize. Returning to the foreground doesn't run initialize again | On returning to the foreground, check maintenance status via the game-server response and show your own maintenance-notice screen. Don't rely on the SDK; handle it in the game's lifecycle hooks (onResume, applicationDidBecomeActive). |
| Some users can still connect during maintenance | Only client-side maintenance is applied (server entry-blocking not implemented) | Put a maintenance-mode flag on the game server and verify maintenance status in every game-server API response to block access. Client info can be forged, so don't trust it; keep the final authority for the maintenance decision on the server. |
| It's a mandatory update but the user ignores it and enters the game | The client's forced-update screen fails to block input, or the game server doesn't block old-version clients | In the OperationUI callback, if the user refuses the update, exit the app with finish()/exit(0). At the same time, verify the client-version header on the game server to reject old-version access. |
| The resource (CDN) update isn't applied to some users | The resource check is implemented to happen only at app launch | At each game-entry step (title → lobby entry, etc.), re-query the resource version from the game server, and if a new resource exists, branch to a forced-download screen. |
| A staff account registered on the whitelist is still blocked by the maintenance screen | Not registered on the platform/game whitelist, or registered in the wrong system | Register the platform whitelist in Partners and the game whitelist in the game ops tool separately. The two systems operate independently, so we recommend registering staff accounts in both. |
Sample Code
using Stove.StoveSDK;
Auth.Initialize((Result result) =>
{
OperationUI.HandleResult(result, (Result handled) =>
{
if (handled.IsSuccessful)
{
// Continue the game-entry flow (login → character selection → lobby)
}
else
{
// User chose exit/cancel → handle app exit
}
});
});
Handling App Exit (3.0.0 or later)
From 3.0.0, the SDK no longer force-quits the app when the maintenance, sanction, or force update notice screen is closed. Instead, the OperationUI.handleResult callback result carries a status value, State. Check it and quit the app or block progress in your game. In 2.9.x, the SDK quits the app, so this handling is not needed.
Closing the notice screen returns a success (isSuccessful) result
If you let users into the game based on isSuccessful alone, in 3.0.0 they can keep playing during maintenance, sanctions, or force updates. Check State first in the callback.
State | When it is delivered | What to do in the game |
|---|---|---|
None | Not maintenance, sanction, or force update | Continue as before |
Maintenance | When the maintenance notice is closed | Quit the app or block game entry |
Sanction | When the sanction notice is closed (the existing userInfo["userAction"] = "sanction" is also delivered) | Quit the app or block game entry |
ForceUpdate | When the required update notice is closed | Quit the app or block game entry |
- From 3.0.0 on Android, canceling an optional update and closing the withdrawal-request or dormant-account notice pop-ups return a cancel (
isCanceled) result instead of success. This matches iOS.
OperationUI.HandleResult(result, (Result handled) =>
{
if (handled.State != State.None)
{
// Maintenance, sanction, or force update → quit the app or block game entry
Application.Quit();
return;
}
if (handled.IsSuccessful)
{
// Continue into the game
}
});
Frequently Asked Questions
- Developers Center Usage / Smilegate Publishing Games: stove.developers@smilegate.com
- STOVE Store Onboarding / STOVE Studio: store.support@smilegate.com