Launching Games from the Web

Understanding

This is an integration feature for launching games by invoking the Stove launcher from the web.
You can integrate the flow of Terms Agreement → Game Maintenance Check → Whitelist Check → Launcher Execution using the Stove JS Service module.
It is used in web environments under Stove domains, such as the Stove official website, individual game websites, and launch pages.

Applicable Environment

Game launch integration operates on web service domains that use Stove authentication.
If you need to use an external domain, you must consult with the responsible Stove technical PM in advance, as it requires separate SSL certificate issuance and infrastructure setup.

Category	Environment	Description
Sandbox	https://js-cdn.gate8.com	Development/QA environment. Uses the gate8 domain.
Live	https://js-cdn.onstove.com	Production environment. Uses the onstove domain.
Web Domain	xxx.game.onstove.com	Recommended domain format when using Stove authentication.

Components

Game launching operates by combining four Stove JS Service modules.
You can choose to integrate by using a package that bundles the modules together (launcher-pack.js) or by calling individual modules separately.

Module	File	Role
LauncherService	launcher.js launcher-pack.js	Handles launcher execution and download URL retrieval.
MaintenanceService	maintenance.js	Checks the game maintenance status. The criteria for blocking execution during maintenance.
WhiteUserService	white-user.js	Identifies whitelisted users who should be allowed to run the game even during maintenance.
StoveTermsService	stove-terms.js	Checks whether the user has agreed to the game service terms. If not agreed, it redirects to the integrated terms page.

Operating Principle

When the game launch button is clicked, checks are performed internally in the order of Terms → Maintenance → Whitelist User → Launcher Execution.
Each step determines the entry conditions for the next step.

Step	Check Item	Branch on Failure
1. Terms of Service	Whether the Terms of Service are agreed to	Redirect to the integrated terms page for consent processing.
2. Game Maintenance	Whether maintenance is currently in progress (REGULAR / TEMPORARY / URGENT)	Block execution after displaying maintenance notice. Whitelisted users are allowed.
3. Whitelist	Whether the logged-in user is a whitelisted user	During maintenance, general users are blocked, while whitelisted users are allowed.
4. Launcher Execution	Whether the launcher is installed and execution protocol call	If not installed, provide download URL.

launcher.run({}) This flow is handled automatically within the method.
However, for automatic checks to work, the window.stoveJsService.maintenance object and the window.stoveJsService.whiteUser object must exist beforehand.
In other words, to use maintenance checks and whitelisted user checks, you must load and initialize the corresponding modules in advance.

There are conditions for maintenance and whitelisted user checks to run
window.stoveJsService.maintenance If the object exists and the isSkipMaintenance value is false, the maintenance check runs.
window.stoveJsService.whiteUser If the object exists and the maintenance check result is true, the whitelisted user check runs.

Integration Guide

Preparation for Integration

Infrastructure To use Stove authentication, the web service (official site) domain must be in the xxx.game.onstove.com format. If integrating with an external official site, SSL certificate issuance and separate infrastructure configuration are required, which can be obtained through the assigned Stove Technical PM.

Code Issuanceinflow_path is a value used to identify the user acquisition path. Obtain it through the assigned Stove Technical PM.

Basic Integration Structure

CDN Domain The Stove JS Service library is provided via CDN for each environment. You must change the Host value when switching from Sandbox testing to Live.

Environment	CDN Domain
Sandbox	https://js-cdn.gate8.com
Live	https://js-cdn.onstove.com

Library Path For quick integration, the packaging method is recommended. The individual method allows you to select and connect only the necessary libs depending on the features used.

Method	lib Path
Packaging method	/libs/stove-js-service/latest/launcher-pack.js (Launcher / Maintenance / White-user integration)
Individual method - Launcher	/libs/stove-js-service/latest/launcher.js
Individual method - Maintenance	/libs/stove-js-service/latest/maintenance.js
Individual method - White-user	/libs/stove-js-service/latest/white-user.js
Terms of Service	/libs/stove-js-service/latest/stove-terms.js

script tag locationhead or body Define it at the very bottom. defer Use the option to ensure the script executes after all content has finished downloading.

Please be sure to apply the defer option
The script tag option should be set to defer so that the script executes after all content has finished downloading.
If it executes immediately without defer, the module initialization may proceed before the DOM is ready, which can cause it to not function properly.

Development

Connecting the Library

Packaging method

The packaging method is a way to integrate launcher execution, maintenance, and white-user checks all at once.

<html>
<head>
    <meta charset="UTF-8">
    <title>stove launcher</title>
</head>
<body>
    // ...컨텐츠 내용 생략
    <script src="https://js-cdn.gate8.com/libs/stove-js-service/latest/launcher-pack.js" defer />
</body>
</html>

Individual method

The individual method connects the lib for each feature (launcher execution, maintenance, white-user) depending on the usage.

<html>
<head>
    <meta charset="UTF-8">
    <title>stove launcher</title>
</head>
<body>
    // ...컨텐츠 내용 생략
    <script src="https://js-cdn.gate8.com/libs/stove-js-service/latest/white-user.js" defer />
    <script src="https://js-cdn.gate8.com/libs/stove-js-service/latest/maintenance.js" defer />
    <script src="https://js-cdn.gate8.com/libs/stove-js-service/latest/launcher.js" defer />
</body>
</html>

Launcher Execution

launcher.run({}) Execute the launcher via the method. Maintenance and white-user checks are handled automatically internally.

Parameter

Parameter	Type	Requirement	Default Value	Description
gameId	String	Y	-	Game ID or Game Number
nation	String	N	KR	Refer to cookie value `NNTO` If there is no cookie information, defaultValue = `'KR'`
lang	String	N	EN	Refer to cookie value `LOCALE` Reference If there is no cookie information, defaultValue = `'EN'`
inflow_path	String	N	-	Same as game ID
isSkipMaintenance	Boolean	N	false	Whether to check for maintenance Default value is to use maintenance check
gameMarketName	String	N	PC_MARKET	When running the launcher from the web, defaultValue = `'PC_MARKET'`
executeWaitingTime	Number	N	5	Execution delay expiration check time (in seconds)

isSkipMaintenance : true
Set this to true if you do not want to use the game maintenance check on the web.
If this parameter is set, even whitelisted users will not be checked.

Example (Promise)

When you call the launcher method (launcher.run({})), you can receive the result value through the then/catch methods of the Promise object.

window.stoveJsService.launcher.run({
    gameId: 'STOVE_EPIC7',
    nation: 'KR',
    lang: 'KO',
    isSkipMaintenance: true
})
.then(data => {
    console.log('런처 실행 성공시 처리', data);
})
.catch(error => {
    console.log('런처 실행 실패시 처리', error);
});

Example (HTML integration usage example)

<html>
<head>
    <meta charset="UTF-8">
    <title>stove launcher</title>
    <script src="https://js-cdn.gate8.com/libs/stove-js-service/latest/launcher-pack.js" defer />
    <script>
        function initializeJsService() {
            window.stoveJsService = window.stoveJsService || {};
        }

        function startLoadingForLauncher() {
            // 런처 실행 로딩 시작 UI 처리
        }

        function stopLoadingForLauncher() {
            // 런처 실행 로딩 종료 UI 처리
        }

        function errorHandler( errorCode ) {
            switch (errorCode) {
                case 601:
                    // 런처가 설치되어 있지 않습니다. 런처를 다운로드한 다음 설치해주세요.
                    break;
                case 602:
                    // 런처 URI가 없는 경우 반환합니다.
                    break;
                case 'API 리턴 오류 코드':
                    // 런처, 점검 그리고 화이트유저 api 호출 시 발생한 오류에 대한 처리가 필요한 경우 case 추가 정의
                    break;
                default:
                    // 기타 오류 공통 처리
                    break;
            }
        }

        function runLauncher() {
            if (!window.stoveJsService.launcher) {
                alert('현재 런처 실행 준비가 되어 있지 않습니다!')
                return;
            }

            startLoadingForLauncher();

            window.stoveJsService.launcher.run({
                gameId: 'STOVE_EPIC7'

            }).then(() => {
                // 런처 실행 성공 시 처리

            }).catch(error => {
                // 런처 실행 실패시 처리
                errorHandler(error.code)

            }).finally(() => {
                stopLoadingForLauncher();
            });
        }
    </script>
</head>
<body onload="initializeJsService">
    <button onclick="runLauncher">게임 실행</button>
</body>
</html>

Error Code

Error Code	Constant	Description
601	NOT_FOUND_LAUNCHER	Returned when the launcher is not installed in the client environment
602	NOT_FOUND_PROTOCOL_URI	Returned when launcher Protocol URI information is missing
503100	GAME_MAINTENANCE	Returned when the executed game service is under maintenance
-	-	If exception handling for individual codes per API response is required, `Error Status Handling List` please refer to the document.

Launcher Download

launcher.download({}) You can query the launcher download URL through the method. It is cached in memory for 60 seconds.

Parameter

Property	Type	Requirement	Description
gameId	String	Y	The gameId parameter is mandatory, and you must pass either `gameId` or `gameNo`. `gameNo` When passed, it is internally converted to the final `gameId` for processing.
nation	String	N	The nation parameter is optional. If omitted, it refers to the local cookie value `NNTO`. If there is no cookie information, the default value is `'KR'`.
lang	String	N	The lang parameter is optional. If omitted, it refers to the local cookie value `LOCALE`. If there is no cookie information, the default value is `'EN'`.

Example (Promise)

stoveJsService.launcher.download({
    gameId : 'STOVE_EPIC7',
    nation : 'KR',
    lang : 'KO'

}).then(url => {
    console.log('url =>', url);

}).catch(error => {
    console.log('error =>', error.code, error.message);
})

Response (Download URL)

'https://sgs-gate8-dl.game.playstove.com/game/lcs/STOVESetup_SGA.exe'

Error Code

Terms Check

stoveTerms.checkAgreeState({}) Use this method to check whether the user has agreed to the Terms of Service.

Parameter

Property	Type	Requirement	Description
service_id	String	Y	The game_id parameter is mandatory. Example: `service_id='STOVE_EPIC7'`
viewarea_id	String	Y	This is the identifier for checking the Terms of Service agreement. Use the `SVC_AG` code as the default value when integrating Terms of Service on the official website.
nation	String	Y	The nation parameter is mandatory and must be passed as an uppercase country code. Example: `KR`, `JP`, `TW`

Example (Promise)

stoveJsService.stoveTerms.checkAgreeState({
    service_id: 'STOVE_EPIC7',
    viewarea_id: 'STC_REWE',
    nation: 'KR'

}).then(isAgreeState => {
    console.log('isAgreeState =>', isAgreeState);

}).catch(error => {
    console.log('error =>', error.code, error.message);
});

Response (Terms Agreement Status)

true

Error Code

Maintenance Inquiry

maintenance.retrieveData({}) Use the method to check the game maintenance status.

Parameter

Property	Type	Requirement	Description
category	String	Y	The category parameter is required; pass `gameId` or `gameNo`.
service_id1	String	Y	The service_id1 parameter is required; pass the `game_id` or `service_id` value.
service_id2	String	Y	The service_id2 parameter is required; PC games basically use the `'PC_MARKET'` value. You can use a custom market name if necessary.
lang	String	N	The lang parameter is optional; pass it if you want to receive information in a specific language only. If no language value is specified, it returns information based on the default language registered in Partners.

Response

Property	Type	Requirement	Description
isInMaintenance	Boolean	-	Returns the maintenance status. - Under maintenance: `true` - In operation: `false`
maintenanceNo	Number	-	Maintenance number
type	String	-	Returns the maintenance type. - `REGULAR`: Regular maintenance - `TEMPORARY`: Temporary maintenance - `URGENT`: Emergency maintenance
title	String	-	Maintenance title
content	String	-	Maintenance content
startDt	Number	-	Maintenance start date (UTC) milli-timestamp (13 digits)
endDt	Number	-	Maintenance end date (UTC) milli-timestamp (13 digits)

Example (Promise)

stoveJsService.maintenance.retrieveData({
    category: 'STOVE_EPIC7',
    service_id1: 'KR',
    service_id2: '',
    lang: 'KO'

}).then(model => {
    console.log('model =>', model);

}).catch(error => {
    console.log('error =>', error.code, error.message);
});

Response (Maintenance Information)

{
    isInMaintenance: true,
    maintenanceNo: 95',
    type: 'REGULAR',
    title: '임시 점검',
    content: '일시적인 접속 지연이 발견되어 임시 점검 진행합니다.',
    startDt: 22783279472389,
    endDt: 247832793489304
}

White User Check

whiteUser.checkStatue({}) Identifies whether the user is a whitelist user allowed to access during maintenance via the method.

Parameter

Property	Type	Requirement	Description
category	String	Y	The category parameter is required and passes the `'GAME'` value.
service_id1	String	Y	The service_id1 parameter is mandatory and `game_id` value is passed.

Example (Promise)

stoveJsService.whiteUser.checkStatue({
    category: 'PLATFORM',
    service_id1: 'STOVE_EPIC7'

}).then(isWhiteUser => {
    console.log('isWhiteUser =>', isWhiteUser);

}).catch(error => {
    console.log('error =>', error.code, error.message);
});

Response (Status information for white users)

true

Error Code

Navigate to Integrated Terms Page

If the "Game Terms of Service Agreement" for a game linked via web service has not been completed, you can link to the terms agreement page provided by STOVE.

Host

Host: 
    https://policy.gate8.com (SANDBOX)
    https://policy.onstove.com (Live)

Parameter (Query String)

Name	Type	Required	Default Value	Example	Description
inflow_path	String	Y	Terms entry point (usage)	-	Information about the terms entry point. Inquire with the technical PM in charge
game_id	String	Y	Game ID	-	Information about the game_id. Inquire with the technical PM in charge
redirect_url (Recommended)	String	N	URL to redirect to after agreeing to terms	-	The URL of the page to navigate to after agreeing to terms or if an error occurs. 1. If redirect_url is provided, it will always navigate to the redirect_url instead of the agreement completion page. 2. If redirect_url is provided, it will always navigate to the redirect_url regardless of the inflow_path value.
show_play_button	String	N	Whether to display the "Play Game" button on the terms agreement completion page	"N"	- Y: The "Play Game" button is displayed instead of the "Confirm" button on the completion page. - N: The "Confirm" button is displayed on the completion page.

Sample Request (goPolicyTerms)

protected goPolicyTerms() {
  window.location.href = `https://policy.onstove.com?inflow_path=STOVE_GAME_ID&game_id=STOVE_GAME_ID&redirect_url=${encodeURIComponent(window.location.href)}`;
}

Return Code (page)

Code	Message	Description
1	Invalid access. Please try again.	Minimum required values for the terms agreement flow For game_id and inflow_path values, inquire with the technical PM
2	This service requires login.	When accessed while not logged in Terms agreement cannot be processed while not logged in
3	The current connection is unstable. Please try again later.	Failed to query game information API Check game_id or game_no
4	The current connection is unstable. Please try again later.	Failed to query terms agreement status API Check partner terms settings
5	This account has already agreed to the terms. Please launch the game.	No need to provide the terms agreement flow if already agreed Block duplicate account terms agreement flow
6	The current connection is unstable. Please try again later.	Cannot determine terms exposure policy. Check partner information 1) Register game information 2) Register service (age) rating information 3) Register footer company information
7	You are not of the required age to use this service.	Check age rating in partner settings
8	The current connection is unstable. Please try again later.	Cannot verify identity or age information
10	This service requires identity verification. Would you like to proceed with identity verification?	-
11	The current connection is unstable. Please try again later.	Identity verified but age information is missing
12	The current connection is unstable. Please try again later.	Check partner terms information registration
13	Invalid access. Please try again.	When game_no is passed in the game_id field
14	This service requires age verification.	For accounts requiring date of birth input in the global flow

#### Integrated Error Code by Service
- LauncherService

Code	Constant	Exception Class	Description
40101	INVALID_ACCESS_TOKEN	AuthenticationException	The token information is invalid.
70051	INVALID_REQUEST	InvalidRequestException	Error in parameter transmission or omission during API call
500000	INTERNAL_SERVER_ERROR	InternalServerExeption	An error occurred during patching. (Common error code)
503100	GAME_MAINTENANCE	UnderMaintenanceException	The game cannot be launched because it is under maintenance. Please try again after the maintenance ends. Error response example json `{ code: 12, message: "에러 내용", data: { maintenanceNo: 12, type: "REGULAR", // TEMPORARY \| URGENT title: "점검 명", content: "점검 내용", startDt: UTC기준 생성일, endDt: UTC기준 생성일 } }` Date unit: milli-timestamp(13digit)
403101	ACCOUNT_LOCKED	-	This account is restricted from using the service. Please check your sanction history for more details.
403102	ACCOUNT_PROTECTED	-	This account is currently protected according to our security policy.
403103	ACCOUNT_CI_RESTRICTION	-	This account is restricted from using the service. Please contact Customer Support.
403201	GAME_EXECUTION_RESTRICTION	-	The requested service is restricted for the following reason.
403202	PERSON_VERIFY_RESTRICTION	-	Restriction Notice (Optional Identity Verification). The requested service is restricted for the following reason. Please contact Customer Support for inquiries regarding restrictions or appeals.
403300	INDIE_RESTRICTION	-	Indie Sanction
406101	UNRELEASED_SVC	-	This is the pre-download period. Please check the official website for the official launch schedule.
406102	UNABLE_CLIENT	-	This is a period where the service is unavailable (client).
406201	UNSERVICEABLE_COUNTRY	-	%GameName% cannot be played in this country.
406202	UNAVAILABLE_COUNTRY_SERVICE	-	%GameName% cannot be played in this country.
406203	UNAVAILABLE_COUNTRY_COPYRIGHT	-	%GameName% cannot be played in this country.
406300	REQUIRED_BIRTH_DAY	-	Age verification is required to play the game.
406301	PROHIBITED_RATING_AGE	-	You are not of the required age to play this game.
406302	PERSON_VERIFY_REQUIRED	-	Identity verification is required. Please proceed with verification.
406303	PARENT_VERIFY_REQUIRED	-	This account requires parental consent. Please proceed with parental consent.
406304	EMAIL_VERIFY_REQUIRED	-	Email verification is required. Please proceed with verification.
406400	REQUIRED_TERMS_AGREE	-	You must agree to the Terms of Service to play the game.
406701	REQUIRED_CANCEL_USE_SERVICE	-	This account has terminated its game service. You must cancel the termination to play the game.
701	NOT_FOUND_GAME	NotFoundGameException	Game information could not be found.

MaintenanceService / WhiteUserService

Code	Constant	Exception Class	Description
40101	INVALID_ACCESS_TOKEN	InvalidAccessTokenException	Invalid access token.
70051	INVALID_REQUEST	InvalidRequestException	Invalid parameter request.

StoveTermsService

Code	Constant	Exception Class	Description
40103	EXPIRED_ACCESS_TOKEN	ExpiredAccessTokenException	The token has expired.
70051	INVALID_REQUEST	InvalidRequestException	Invalid input value.
70800	NOT_EXIST_TERMS	BasicBusinessException	The terms and conditions do not exist.
70804	GS_NETWORK_ERROR	BasicBusinessException	A GS integration network error has occurred.
70805	GUID_NETWORK_ERROR	BasicBusinessException	A GUID integration network error has occurred.
70806	NOT_EXIST_SERVICE_ID	BasicBusinessException	Service ID information could not be found.
70807	UNKNOWN_GUID_SERVER	BasicBusinessException	There is a problem with the GUID service. Please try again later.
70870	NOT_EXIST_CALLER_ID	BasicBusinessException	Please check the caller-id value.
70871	NOT_EXIST_CALLER_DETAIL	BasicBusinessException	Please check the caller-detail value.

Frequently Asked Questions

Q1. What are the criteria for choosing between the packaging method and the individual method?

A. If you are using all of the launcher execution, maintenance check, and white-user check, we recommend the packaging method (launcher-pack.js).
It is faster to integrate because all three modules are initialized simultaneously with a single script load.
If you only use some features or if the usage timing varies by page, you can choose and load only the necessary libs using the individual method.

Q2. What happens if I set isSkipMaintenance to true?

A. It skips the maintenance check. Even during maintenance, the launcher will attempt to execute without notifying the user.
Also, skipping the maintenance check means the white-user check will not function either, so it is recommended to keep it as
false (default) for entry points used by general users, rather than QA pages or admin tools.

Q3. I called launcher.run, but it returns a 601 error after 5 seconds.

A. The executeWaitingTime default is set to 5 seconds, so if there is no response 5 seconds after the launcher execution, it returns a 601 error.
This can occur if the launcher is not installed on the user's PC or if the protocol handler is blocked by security policies.
When a 601 occurs, you must call launcher.download({}) to provide the download URL.

Q4. Can I call the launcher download URL repeatedly?

A. launcher.download({}) returns the URL cached in memory for 60 seconds.
If called again within 60 seconds, you will receive the same URL quickly, but after 60 seconds, it will query the download API again and return the newly fetched URL.
There is no performance impact from repeated calls within a short time in the same session.

Q5. How do I handle it when the terms check returns false?

A. You should redirect the user to the integrated terms page to prompt them to agree manually.
The redirect URL is in the format of https://policy.gate8.com/?inflow_path=...&game_id=..., and
it is recommended to pass the redirect_url parameter as well if there is a page to return to after agreeing to the terms.

Q6. Can white-users run the game during maintenance?

A. Yes, it is possible. Even if the maintenance check result isInMaintenance is true within launcher.run({}), if the white-user check confirms the user is registered on the whitelist,
the launcher will execute. White-user registration is managed under [Partners] > [GM] > [Client 2.0] > [Client Whitelist].

Q7. Where can I perform integration tests?

A. We provide a dedicated test page for the Sandbox environment.
The integrated test page for STOVE JS Service can be accessed at https://js-cdn.gate8.com/libs/stove-js-service/latest/index.html.
If the sample page does not work properly, please clear your browser cache and try again.

Would you like to contact us directly? stove.developers@smilegate.com