커스텀 웹 로그인 구현¶

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

Note

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

개요¶

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

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

'커스텀 웹 로그인 구현' 기능으로 제공되는 API는 아래와 같습니다.

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

IdP 로그인¶

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

Warning

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

Note

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

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/auth/signinidp
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/signinidp
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request body¶

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

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "idp_index": 3,
    "idp_user_id": "google_67890",
    "require_token": true
}

Response header¶

require_token: true인 경우 다음 헤더가 포함됩니다.

필드명	설명	타입
Authorization	세션 토큰. 계정 삭제 API 호출 시 사용	String

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 오류)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String
data	결과 데이터	Object
data.player_id	Player ID	Integer
data.idp_index	IdP 인덱스	Integer
data.idp_id	IdP 이름	String
data.idp_user_id	IdP 사용자 ID	String

Response example¶

성공¶

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

응답 코드¶

코드값	설명
0	성공
2499	JWT 검증 실패 (token_validation 참고)
4200	존재하지 않는 IdP
5000	서버 내부 오류

IdP 연동¶

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

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/auth/connect
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/connect
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request body¶

필드명	설명	타입	필수 여부
appid	App ID	String	Y
idp_index	IdP 인덱스 코드 (IdP 리스트 참고)	Integer	Y
idp_user_id	IdP 사용자 고유 식별자	String	Y
player_id	연동할 Player ID	Integer	Y

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001
}

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 오류)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String
data	결과 데이터	Object
data.player_id	Player ID	Integer
data.idp_index	연동된 IdP 인덱스	Integer
data.idp_id	연동된 IdP 이름	String
data.idp_user_id	IdP 사용자 ID	String

Response example¶

성공¶

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

이미 다른 플레이어에 연동된 경우¶

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

응답 코드¶

코드값	설명
0	성공
1002	해당 IdP가 다른 플레이어에 이미 연동됨
1003	동일한 IdP 타입이 이미 연동됨
2002	존재하지 않는 플레이어
2499	JWT 검증 실패 (token_validation 참고)
4200	존재하지 않는 IdP
5000	서버 내부 오류

IdP 연동 해제¶

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

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/auth/disconnect
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/disconnect
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request body¶

필드명	설명	타입	필수 여부
appid	App ID	String	Y
idp_index	IdP 인덱스 코드 (IdP 리스트 참고)	Integer	Y
idp_user_id	IdP 사용자 고유 식별자	String	Y
player_id	Player ID	Integer	Y

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001
}

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 오류)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String

Response example¶

성공¶

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

응답 코드¶

코드값	설명
0	성공
2499	JWT 검증 실패 (token_validation 참고)
4006	연동된 IdP 정보 없음
4200	존재하지 않는 IdP
5000	서버 내부 오류
7000	유효하지 않은 토큰

계정 삭제¶

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

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

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

Warning

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

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/player/delete-project
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/player/delete-project
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y
Authorization	IdP 로그인 호출 시 `require_token: true` 설정 후 응답 헤더로 전달받은 세션 토큰	String	Y

Request body¶

필드명	설명	타입	필수 여부
appid	App ID	String	Y
player_id	삭제할 Player ID	Integer	Y
did	디바이스 ID. `0` 고정	Integer	Y

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "player_id": 100000001,
    "did": 0
}

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 오류)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String

Response example¶

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

응답 코드¶

코드값	설명
0	성공
2499	JWT 검증 실패 (token_validation 참고)
5000	서버 내부 오류
7000	유효하지 않은 토큰
7001	헤더에 토큰 없음

Note

JWT 검증 실패 시, token_validation 필드로 상세한 오류 정보를 확인할 수 있습니다. 자세한 내용은 JWT 검증 오류 코드를 참고하세요.