커스텀 웹 로그인 구현¶

하이브 플랫폼에서 제공하는 웹 로그인 페이지를 사용하지 않고 하이브 서버 API를 활용하여 직접 웹 로그인을 구현하는 방법을 안내합니다. 개발사가 자체 로그인 UI를 구성하고 IdP 인증을 직접 처리하려는 경우 이 문서를 참고하세요.

Note

커스텀 웹 로그인 API를 사용하려면 하이브 콘솔에서 앱 등록 및 hive_certification_key 발급이 완료되어야 합니다.

개요¶

커스텀 웹 로그인은 다음과 같은 경우에 사용합니다.

개발사 고유의 로그인 UI/UX를 적용하고 싶은 경우
기존 웹사이트 디자인과 통일된 로그인 화면을 구현하고 싶은 경우
웹 로그인 페이지로 리다이렉트 없이 자체 페이지 내에서 로그인을 처리하고 싶은 경우

API 목록¶

API Endpoint	설명
`POST /game/auth/signinidp`	IdP 로그인
`POST /game/auth/connect`	IdP 연동
`POST /game/auth/disconnect`	IdP 연동 해제
`POST /game/player/delete`	계정 삭제

공통 요청 헤더¶

헤더명	타입	필수 여부	설명
Content-Type	String	Y	`application/json` 고정
Authorization	String	Y or N	세션 토큰. 토큰 검증이 필요한 API에서 필수, 그렇지 않으면 생략 가능
ISCRYPT	Integer	Y	암호화 여부. `0`값으로 고정

공통 응답 헤더¶

헤더명	타입	설명
Authorization	String	신규 발급된 세션 토큰. IdP 로그인 요청 시 `require_token: true`인 경우에만 발급
ISCRYPT	Integer	응답 암호화 여부

공통 응답 형식¶

성공 응답¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": { }
}

실패 응답¶

{
    "result_code": 4000,
    "result_msg": "Request has invalid format.",
    "data": null
}

IdP 로그인¶

IdP 정보로 신규 플레이어를 생성하거나, 이미 등록된 IdP인 경우 기존 플레이어 정보를 반환합니다. 로그인 성공 시 data.player_id로 PlayerID를 확인할 수 있습니다.

Warning

커스텀 웹 로그인 API는 게스트(GUEST, idp_index: 0) 계정 생성을 지원하지 않습니다.

Note

계정 삭제 API를 사용하려면 require_token을 true로 설정하여 응답 헤더의 Authorization 값을 발급받아야 합니다. 계정 삭제 기능을 사용하지 않는 경우 false로 설정할 수 있습니다.

Request URL¶

환경	URL
상용 (Production)	`https://auth.qpyou.cn/game/auth/signinidp`
샌드박스 (Sandbox)	`https://sandbox-auth.qpyou.cn/game/auth/signinidp`
HTTP Method	`POST`
Content-Type	`application/json`

Request Body¶

필드명	타입	설명	필수 여부
appid	String	게임 앱 ID (`AppID`)	Y
idp_index	Integer	IdP 인덱스 코드. IdP 코드 정의 참고	Y
idp_user_id	String	IdP 사용자 고유 식별자	Y
hive_certification_key	String	하이브 인증키	Y
require_token	Boolean	플레이어 토큰 요청 여부. 계정 삭제 API 사용 시 `true`, 미사용 시 `false`	Y

Request Body Example¶

{
    "appid": "com.com2us.example",
    "idp_index": 3,
    "idp_user_id": "google_67890",
    "hive_certification_key": "your_certification_key",
    "require_token": true
}

Response Header¶

필드명	타입	설명
Content-Type	String	응답 데이터 형식(JSON) 및 문자 인코딩(UTF-8) 정보
Authorization	String	세션 토큰

Response Header Example¶

HTTP/1.1 200
Content-Type: application/json; charset=UTF-8
Authorization: abcdf7ebce779429ea878f91d5f1c8
Iscrypt: 0

Response Body¶

필드명	타입	설명
result_code	Integer	결과 코드. `0`이면 성공
result_msg	String	결과 메시지
data.player_id	Integer	`PlayerID`
data.idp_index	Integer	IdP 인덱스
data.idp_id	String	IdP 이름
data.idp_user_id	String	IdP 사용자 ID

Response Body Sample (성공)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": {
        "player_id": 100000002,
        "idp_index": 3,
        "idp_id": "GOOGLE",
        "idp_user_id": "google_67890"
    }
}

Response Body Sample (실패)¶

{
    "result_code": 4002,
    "result_msg": "Invalid certfication key"
}

오류 코드¶

코드	설명	비고
4002	인증 키 오류
4200	존재하지 않는 IdP
5000	데이터베이스 오류

IdP 연동¶

기존 플레이어 계정에 새로운 IdP를 연동합니다. 반드시 IdP 로그인 API로 로그인한 후 호출해야 합니다.

Request URL¶

환경	URL
상용 (Production)	`https://auth.qpyou.cn/game/auth/connect`
샌드박스 (Sandbox)	`https://sandbox-auth.qpyou.cn/game/auth/connect`
HTTP Method	`POST`
Content-Type	`application/json`

Request Body¶

필드명	타입	설명	필수 여부
appid	String	게임 앱 ID (`AppID`)	Y
idp_index	Integer	IdP 인덱스 코드. IdP 코드 정의 참고	Y
idp_user_id	String	IdP 사용자 고유 식별자	Y
player_id	Integer	연동할 `PlayerID`	Y
hive_certification_key	String	하이브 인증키	Y

Request Body Example¶

{
    "appid": "com.com2us.example",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001,
    "hive_certification_key": "your_certification_key"
}

Response Body¶

필드명	타입	설명
result_code	Integer	결과 코드. `0`이면 성공
result_msg	String	결과 메시지
data.player_id	Integer	`PlayerID`
data.idp_index	Integer	연동된 IdP 인덱스
data.idp_id	String	연동된 IdP 이름
data.idp_user_id	String	IdP 사용자 ID

Response Body Sample (성공)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": {
        "player_id": 100000001,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

Response Body Sample (다른 플레이어에 이미 연동된 경우)¶

{
    "result_code": 1002,
    "result_msg": "Already connected other player",
    "data": {
        "player_id": 100000002,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

오류 코드¶

코드	설명	비고
1002	해당 IdP가 다른 플레이어에 이미 연동됨
1003	동일한 IdP 타입이 이미 연동됨
2002	존재하지 않는 플레이어
4002	인증 키 오류
4200	존재하지 않는 IdP
5000	데이터베이스 오류

IdP 연동 해제¶

플레이어 계정에서 연동된 IdP를 해제합니다. 반드시 IdP 로그인 API로 로그인한 후 호출해야 합니다.

Request URL¶

환경	URL
상용 (Production)	`https://auth.qpyou.cn/game/auth/disconnect`
샌드박스 (Sandbox)	`https://sandbox-auth.qpyou.cn/game/auth/disconnect`
HTTP Method	`POST`
Content-Type	`application/json`

Request Body¶

필드명	타입	설명	필수 여부
appid	String	게임 앱 ID (`AppID`)	Y
idp_index	Integer	IdP 인덱스 코드. IdP 코드 정의 참고	Y
idp_user_id	String	IdP 사용자 고유 식별자	Y
player_id	Integer	`PlayerID`	Y
hive_certification_key	String	하이브 인증키	Y

Request Body Example¶

{
    "appid": "com.com2us.example",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001,
    "hive_certification_key": "your_certification_key"
}

Response Body¶

필드명	타입	설명
result_code	Integer	결과 코드. `0`이면 성공
result_msg	String	결과 메시지

Response Body Sample (성공)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS"
}

Response Body Sample (실패)¶

{
    "result_code": 4002,
    "result_msg": "Invalid certfication key"
}

오류 코드¶

코드	설명	비고
4002	인증 키 오류
4006	연동된 IdP 정보 없음
4200	존재하지 않는 IdP
7000	유효하지 않은 토큰

계정 삭제¶

플레이어 계정을 삭제합니다. 반드시 IdP 로그인 API로 로그인한 후 호출해야 합니다.

이 API는 토큰 검증이 필수이므로 반드시 다음 작업을 선행해야 합니다.

IdP 로그인 API 호출 시 require_token을 true로 설정
IdP 로그인 API 응답 헤더로 전달받은 Authorization 값을 저장
이 API 호출 시 요청 헤더에 위에서 저장한 Authorization 값을 포함

Warning

계정 삭제는 되돌릴 수 없습니다. 삭제 전 사용자에게 충분한 안내를 제공하세요.

Request URL¶

환경	URL
상용 (Production)	`https://auth.qpyou.cn/game/player/delete`
샌드박스 (Sandbox)	`https://sandbox-auth.qpyou.cn/game/player/delete`
HTTP Method	`POST`
Content-Type	`application/json`

Request Header¶

헤더명	타입	설명	필수 여부
Authorization	String	IdP 로그인 호출 시 `require_token: true` 설정 후 응답 헤더로 전달받은 세션 토큰	Y

Request Body¶

필드명	타입	설명	필수 여부
appid	String	게임 앱 ID (`AppID`)	Y
player_id	Integer	삭제할 `PlayerID`	Y
did	Integer	디바이스 ID. `0` 고정	Y
hive_certification_key	String	하이브 인증키	Y

Request Body Example¶

{
    "appid": "com.com2us.example",
    "player_id": 100000001,
    "did": 0,
    "hive_certification_key": "your_certification_key"
}

Response Body¶

필드명	타입	설명
result_code	Integer	결과 코드. `0`이면 성공
result_msg	String	결과 메시지

Response Body Sample (성공)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS"
}

Response Body Sample (실패)¶

{
    "result_code": 7000,
    "result_msg": "Invalid token."
}

오류 코드¶

코드	설명	비고
4002	인증 키 오류
7000	유효하지 않은 토큰
7001	헤더에 토큰 없음

IdP 코드 정의¶

기본 IdP¶

코드	IDP_ID	설명
0	GUEST	게스트
1	HIVE	멤버십 계정
2	FACEBOOK	Facebook
3	GOOGLE	Google
4	QQ	QQ
5	WEIBO	Weibo
6	VK	VK
7	WECHAT	WeChat
8	APPLE	Apple Game Center
9	SIGNIN_APPLE	Sign in with Apple
10	LINE	LINE
11	TWITTER	Twitter
12	WEVERSE	Weverse
13	NAVER	Naver
14	GOOGLE_PLAY_GAMES	Google Play Games
15	HUAWEI	Huawei
16	FUNTAP	Funtap
18	STEAM	Steam
19	X	X (구 Twitter)
20	TELEGRAM	Telegram
21	XIAOMI	Xiaomi
22	OPPO	OPPO
23	VIVO	VIVO

커스텀 IdP¶

코드	IDP_ID	설명
1100	CUSTOM_GAME	게임사 자사 제공 IdP