For the complete documentation index, see llms.txt. This page is also available as Markdown.

ONEquest Development Guide

ONEquest is a marketing tool that lets developers set up goal-based quests at any time they choose to drive ONE store users to engage with their games. To offer in-game action quests, the developer needs to do development work so that ONEquest can be told whether an in-game action has been completed.

1. Overview

When a quest participant completes a specific in-game action (quest) and claims the reward, the ONEquest server calls the game company's API to verify completion in real time. The game company must build and provide two APIs that follow the specifications in this document.

API
When it's called
Role

first links their account

Checks that the game_user_id exists on your game server

claims a reward

Checks in real time whether the player finished the quest

Both APIs are server-to-server calls from the ONEquest server to the developer. No extra development is needed in the game client (app). There is no API for the game company to call ONEquest.

2. Integration Process

To make reward payouts reliable and keep things easy for users, the integration runs in two phases: ① initial account linking and ② in-game action verification.

Phase 1. Initial account linking (per user)

#
Who
Actions

1

User

Enters their game ID (game_user_id) and taps Link

2

ONEquest

Calls your User Validation API

3

Game Server

Checks that the player exists and returns success

4

ONEquest

If the player is valid, saves the game_user_id and reuses it for every quest in the same quest group

Phase 2. In-game action verification (each time a reward is claimed)

#
Who
Actions

1

User

Finishes the quest and taps Claim Reward, with no ID needed

2

ONEquest

Calls your Quest Verification API with the saved game_user_id

3

Game Server

Looks up the player's progress and returns the result

4

ONEquest

Grants the reward based on the result

Each game_user_id can be linked to only one ONE store account, so one player can't take part twice.

3. Prerequisites

3.1 Development Requirements

Item
Requirement

Protocol

HTTPS recommended (HTTP needs our approval). Use a domain name as the host, not an IP address.

Response time (SLA)

Respond within 500 ms.

Data format

JSON for request and response bodies (Content-Type: application/json).

User ID

Receive game_user_id as a query parameter, whatever the HTTP method. It's the only required parameter.

Endpoint

Use any path and host you like, but the request and response formats must follow this spec.

Redirects

The registered URL must be final. ONEquest doesn't follow 3xx redirects.

3.2 Firewall Allow list IPs

Because the ONEquest server calls the game company's APIs, the game company's server (firewall) must allow inbound access from the ONEquest source IPs below.

Environment
Source IP to allow

Dev (QA)

211.188.207.190

Prod

211.188.201.250

3.3 Console Registration

Developers register their APIs themselves in the Developer Center under ONEconsole > Quest. ONEquest calls the registered URL with only the game_user_id query parameter added.

Registered for
Items
Details

Quest group

One per group

Quest (in-game action)

One per quest. We recommend putting your own quest ID in the path.

The registration screen includes a connectivity test:

  • It sends a real request to the URL you entered to check that the URL can be reached and that the response follows the spec. You must pass this test before you can register a quest.

  • The test only checks that the endpoint can be reached and returns JSON in the correct format, so it passes whether the result is "completed" or "not completed."

  • If you change the URL or the HTTP method, you must run the test again.

4. game_user_id

Both APIs take a single required user identifier parameter: game_user_id.

Item
Spec

Type

String

Format

Standard 36-character UUID (8-4-4-4-12)

Max length

255 characters

Sent as

Query parameter, whatever the HTTP method

Example

13f664fc-3d8a-f011-94e3-e0451a3b66b3

5. User Validation API

When a ONEquest user links their game account for the first time, this API checks whether the game_user_id they entered actually exists on the game server.

5.1 Request

Item
Value

Method

GET (example)

Endpoint (example)

https://{Game_Server_Host}/onequest/users/validate?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3

Content-Type

application/json

The endpoint path is only an example. Set it up to suit your game service, then register it in ONEconsole. The request and response data formats can't be changed.

In
Parameter
Type
Required
Description

Query

game_user_id

String

Y

The player's in-game ID to check (UUID, max 255 characters)

Request Example

5.2 Response

Field
Type
Required
Description

success

Boolean

Y

Whether the user exists (true: exists, false: not found)

joined_at

String

N

When the user joined the game, in ISO 8601 with time zone

Success: valid user

Failure: user does not exist

6. In-Game Action Verification API

When a user completes a specific in-game quest and claims the reward, this API checks in real time whether that user actually completed it. It is called at the URL registered in ONEconsole for each quest.

6.1 Request

Item
Value

Method

GET (example)

Endpoint (example)

https://{Game_Server_Host}/onequest/quests/{quest_id}/verify?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3

Content-Type

application/json

In
Parameter
Type
Required
Description

Path

quest_id

String

N

Your own quest ID. ONEquest calls the registered URL exactly as it is and doesn't read it, so your server uses the URL to tell quest conditions apart (level, tutorial, and so on).

Query

game_user_id

String

Y

The user's in-game ID (UUID), saved during Step 1

Request Example

6.2 Response

Based on the verification result, the response must clearly state either completed (true) or not completed (false).

Filed
Type
Required
Description

success

Boolean

Y

Whether the quest was completed (true: completed, false: not completed)

message

String

Y

Result message. Please include the reason when it fails. It's for internal use and isn't shown to players.

Success: quest completed

Failure: quest not completed

Failure: user does not exist

7. Error Handling and Response Codes

If the normal verification logic can't run (for example, during server maintenance), return the appropriate HTTP status code.

HTTP Code
Status
What it means
What the user sees

200

OK

Handled normally. success in the body says whether the quest was completed.

Completed: reward granted / Not completed: "Conditions not met"

401 / 403

Unauthorized / Forbidden

The request came from an IP that isn't allowed and was blocked.

"Can't check right now." Our ops team is alerted, since the IP may be missing from your allowlist.

500

Internal Server Error

Your server hit an internal error.

"Can't check right now."

503

Service Unavailable

Maintenance or a temporary outage. During maintenance, return 503 right away instead of letting the request time out.

"Game under maintenance."

ONEquest Server Call Policy

Item
Value
Notes

Timeout

Connect 1 s / Read 3 s

If exceeded, the check fails ("Can't check right now"). You won't hit this if you meet the 500 ms SLA.

Retries

None (one call)

Each time the player tries again, ONEquest makes a new call. That's why the verify API must be read-only.

Redirects

3xx not followed, so the check fails

The registered URL must be final.

2xx with a non-JSON body or no success

The check fails

This includes an empty body.

Failure isolation

Blocked per game company

If one company's API keeps failing, ONEquest pauses calls to it for a while and tells players it can't check right now. Other companies' quests aren't affected.

8. Implementation Example

Scenario: A user (game_user_id = 13fc-...) completes the "Reach Level 30" quest (game company Quest ID: 1) and claims the reward.

1

User validation (once, at initial linking)

  • ONEquest request: GET /onequest/users/validate?game_user_id=13f664fc-...

  • Game company response: {"success": true}

  • Result: The user is confirmed as valid, and the link to their ONE store account is saved.

2

In-game action verification

  • ONEquest request: GET /onequest/quests/1/verify?game_user_id=13f664fc-... (Source IP: 211.188.201.250)

  • Game company server logic:

    1. Check that the source IP is on the allowlist → Pass

    2. Look up the user's level in the database → Lv. 32 (condition met)

  • Game company response: {"success": true, "message": "Quest Complete"}

3

Final processing

  • ONEquest: A reward is granted only once per user per quest.

9. Integration Checklist

Last updated