ONEquest 인게임 연동 가이드
ONEquest(원퀘스트)는 게임사가 원하는 시점에 목표에 맞는 퀘스트를 설정하여 원스토어 유저의 게임 참여를 유도할 수 있는 마케팅 도구입니다. 인게임 액션 퀘스트를 제공하려면, 게임 내 액션의 완료 여부를 ONEquest에 전달할 수 있도록 게임사 측 개발 연동이 필요합니다.
1. 개요
퀘스트 이용자가 게임 내 특정 액션(퀘스트)을 달성하고 보상을 신청할 때, 원퀘스트 서버가 게임사 API 를 호출해 달성 여부를 실시간으로 검증합니다. 게임사는 본 문서의 규격에 맞춰 2개의 API 를 구현해 제공해야 합니다.
2. 연동 프로세스
안정적인 보상 지급과 유저 편의를 위해 ① 최초 계정 연동 과 ② 인게임 액션 검증 의 2단계로 동작합니다.
Phase 1. 최초 계정 연동 — 유저당 1회
1
User
게임 ID(game_user_id) 입력 후 '연동하기' 선택
2
원퀘스트
게임사 유저 유효성 확인 API 호출
3
Game Server
유저 존재 여부 확인 후 success 반환
4
원퀘스트
유효한 유저이면 game_user_id 를 저장. 이후 같은 퀘스트 그룹의 모든 퀘스트에 재사용
Phase 2. 인게임 액션 검증 — 보상 신청 시마다
1
User
퀘스트 달성 후 ID 입력 없이 '보상 받기' 선택
2
원퀘스트
저장된 game_user_id 로 게임사 인게임 액션 검증 API 자동 호출
3
Game Server
유저의 퀘스트 달성 데이터 조회 및 결과 반환
4
원퀘스트
결과에 따라 유저에게 리워드 지급
3. 사전 준비 사항
3.1 개발 필수 요건
프로토콜
HTTPS 권장 (HTTP 허용 시 별도 협의). 엔드포인트 호스트는 IP 주소가 아닌 DNS 도메인(호스트명) 으로 제공해 주시기 바랍니다
응답 속도 (SLA)
API 응답은 요청 후 500ms 이내에 완료되어야 합니다
데이터 형식
요청 및 응답 본문은 JSON 형식을 사용합니다 (Content-Type: application/json)
식별자 전달
game_user_id 는 HTTP 메서드 종류와 관계없이 쿼리 파라미터(Query String) 로 수신해야 합니다. 표준이 요구하는 필수 파라미터는 game_user_id 하나입니다
엔드포인트
경로·호스트는 게임 서비스 환경에 맞게 자율 구성 가능합니다. 단 요청·응답 데이터 규격은 반드시 본 표준을 준수해야 합니다
리다이렉트
등록한 URL 이 최종 URL 이어야 합니다. 원퀘스트는 3xx 리다이렉트를 따라가지 않습니다
3.2 방화벽 허용 IP
원퀘스트 서버가 게임사 API 를 호출하므로, 게임사 서버(방화벽)는 아래 원퀘스트 발송 IP(Source IP)에 대해 인바운드 접근을 허용해야 합니다.
개발(QA) 서버
211.188.207.190
운영(상용) 서버
211.188.201.250
3.3 콘솔 등록
구현한 API 는 개발자센터 ONEconsole > Quest 메뉴에서 개발사가 직접 등록합니다. 원퀘스트는 여기 등록된 URL 에 game_user_id 쿼리 파라미터만 붙여 호출합니다.
4. game_user_id
두 API 모두 유저 식별자로 game_user_id 하나만을 필수 파라미터로 사용합니다.
타입
String
형식
UUID — 표준 UUID(36자) 형식 8-4-4-4-12
최대 길이
255자 이내
전달 위치
HTTP 메서드 종류와 관계없이 쿼리 파라미터(Query String) 로 수신
예시
13f664fc-3d8a-f011-94e3-e0451a3b66b3
5. 유저 유효성 확인 API
원퀘스트 이용자가 게임 계정을 최초 연동할 때, 입력한 game_user_id 가 게임 서버에 실제로 존재하는지 확인하는 API 입니다.
5.1 요청 (Request)
Method
GET (예시)
Endpoint (예시)
https://{Game_Server_Host}/onequest/users/validate?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3
Content-Type
application/json
엔드포인트 경로는 예시이며, 게임 서비스 환경에 맞게 구성 후 ONEconsole 에 등록해 주세요. 요청·응답 데이터 규격은 변경할 수 없습니다.
Query
game_user_id
String
Y
검증할 게임 내 유저 식별자 (UUID, 최대 255자)
Request Example
5.2 응답 (Response)
success
Boolean
Y
유효한 유저 여부 (true: 존재함, false: 존재하지 않음)
joined_at
String
N
게임 가입 일시. ISO 8601 형식(타임존 포함)
성공 - 유효한 유저
실패 - 존재하지 않는 유저
6. 인게임 액션 검증 API
유저가 게임 내 특정 퀘스트를 완수하고 보상을 신청하는 시점에, 해당 유저의 실제 달성 여부를 실시간으로 조회·검증하는 API 입니다. 퀘스트마다 ONEconsole 에 등록한 URL 로 호출됩니다.
6.1 요청 (Request)
Method
GET (예시)
Endpoint (예시)
https://{Game_Server_Host}/onequest/quests/{quest_id}/verify?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3
Content-Type
application/json
Path
quest_id
String
N
게임사 자체 퀘스트 식별자. 원퀘스트는 URL 을 해석하지 않고 등록된 URL 그대로 호출하므로, 퀘스트별 조건(레벨·튜토리얼 완료 등)은 게임사 서버가 URL 로 구분합니다
Query
game_user_id
String
Y
게임 내 유저 식별자 (UUID). Phase 1 에서 연동 저장된 값
Request Example
6.2 응답 (Response)
검증 결과에 따라 달성(true) 또는 미달성(false)을 명확히 반환해야 합니다.
success
Boolean
Y
퀘스트 달성 여부 (true: 달성, false: 미달성)
message
String
Y
결과 메시지. 실패 시 사유 포함 권장(운영 확인용이며 유저에게 그대로 노출되지 않습니다)
성공 - 퀘스트 달성
실패 - 퀘스트 미달성
실패 - 존재하지 않는 유저
7. 예외 처리 및 응답 코드
정상적인 검증 로직 수행이 불가능한 경우(서버 점검 등)에는 적절한 HTTP 상태 코드를 반환해야 합니다.
200
OK
정상 처리. Body 의 success 값으로 달성/미달성 판별
달성: 리워드 지급 / 미달성: 조건 미충족 안내
401 / 403
Unauthorized / Forbidden
허용되지 않은 IP 에서의 요청 (보안 차단)
일시적으로 확인할 수 없음. 원퀘스트 운영 알림 대상(허용 IP 누락 의심)
500
Internal Server Error
게임사 서버 내부 오류
일시적으로 확인할 수 없음
503
Service Unavailable
서버 점검 또는 일시적 서비스 불가. 점검 시 타임아웃을 기다리지 않고 즉시 503 을 반환해야 합니다
"게임 점검 중" 안내
원퀘스트 서버의 호출 정책
타임아웃
connect 1초 / read 3초
초과 시 실패(일시적으로 확인 불가) 처리. SLA 500ms 를 지키면 도달하지 않는 값입니다
재시도
없음 (1회 호출)
유저가 다시 시도하면 새 호출이 발생합니다. 검증 API 가 조회 전용이어야 하는 이유입니다
리다이렉트
3xx 미추적 — 실패 처리
등록 URL 이 최종 URL 이어야 합니다
2xx 이지만 본문이 JSON 이 아니거나 success 가 없음
실패 처리
빈 본문 포함
장애 격리
게임사별 차단
특정 게임사 API 실패가 누적되면 일정 시간 호출을 차단하고 유저에게 일시 확인 불가를 안내합니다. 다른 게임사 퀘스트에는 영향이 없습니다
8. 구현 예시
상황: 유저(game_user_id = 13fc-...)가 '레벨 30 달성 (게임사 Quest ID: 1)' 퀘스트를 완료하고 보상을 요청
9. 연동 체크리스트
Last updated