초대 코드 기반 매칭 유저 초대는 유저가 초대 코드를 발급하여 다른 유저를 게임으로 초대하고, 개발사로부터 이에 대한 보상을 받는 기능입니다. 사용자 초대 API는 게임에서 초대 코드를 발급받아 초대를 수락한 사용자를 매칭 할 수 있는 API입니다.
Warning 아래 모든 API에서 Authorization Header는 필수가 아닙니다. 단, 보안을 위해 Hive 인증키 를 사용하고 게임 서버에서 API를 직접 호출하는 것을 권장합니다.
사용 방법 Hive 콘솔 > 프로모션 > 유저 초대 > 초대 캠페인 등록 에서 초대 코드 발급 타입으로 캠페인을 생성 합니다. 초대 캠페인 정보를 조회 해 유효한 캠페인 ID를 게임 서버에 저장합니다. 유저 초대 페이지에서 입력받은 초대자 정보, 위에서 저장한 캠페인 ID를 호출 파라미터로 전달하고 초대 코드를 발급 받습니다. 초대 수락자 정보(player_id
등)와 수락자가 받은 초대 코드를 호출 파라미터로 전달하고 매칭 요청 을 합니다. 보상 현황 확인 하기 를 호출해 유저 초대 페이지에 보상을 받기 위한 진행 상황을 표시합니다. 사전 준비 초대 코드 관련 API를 사용하려면 다음 항목을 준비해야 합니다.
Authorization Header에 사용할 Hive 인증키: Hive 콘솔 > 앱센터 > 프로젝트 관리 > 앱 검색 후 앱 선택 > 게임 상세 > 기본정보 > Hive 인증키 server_id
: Hive 콘솔 > 앱센터 > 프로젝트 관리 > 앱 검색 후 앱 선택 > 게임 상세 > 게임 서버 초대 캠페인: Hive 콘솔 > 프로모션 > 유저 초대 > 초대 캠페인 등록 에서 초대 코드 발급 타입으로 캠페인을 생성 캠페인 정보 조회하기 Hive 콘솔에서 생성한 초대 캠페인 정보를 조회합니다. 활성화되고 사용 가능한 초대 캠페인 정보만 불러옵니다. 응답값으로 캠페인 내 설정된 보상 정보도 같이 전달합니다.
API 요청 명세 Request URL 환경 URL 상용 https://promotion.qpyou.cn/ua/inviteCode/campaign
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign
요청 방식 및 데이터 형식 항목 설명 HTTP Method POST
Content-Type application/json
필드명 설명 타입 필수여부 Authorization Bearer 인증을 통한 certificationKey
유효성 판단 String N
Request Body 필드명 설명 타입 필수여부 gameindex 게임 고유 번호 Integer Y
호출 예제 curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign" \
-H "Content-Type: application/json" \
-d '{
"gameindex": 539
}'
API 응답 명세 Response 필드명 설명 타입 필수여부 result_code 응답 코드 Integer Y result_message 응답 메시지 String Y campaign_list 초대 코드 캠페인 리스트 Array Y ㄴ id 프로모션 캠페인 ID Integer N ㄴ title 캠페인 제목 String N ㄴ rewards 보상 리스트 Array N ㄴㄴ reward_id 보상 ID Integer N ㄴㄴ description 보상 설명 String N ㄴㄴ reward_type 보상 타입 action: 행동 보상 goal: 목표 수 달성 보상 String N ㄴㄴ action_type 행동 타입 match: 매칭 cpi: 설치 cpa: 특정 행동 달성 String N ㄴㄴ cpa_code cpa 고유 번호 행동 타입이 cpa인 경우 유효한 값을 전달 cpa가 아닌 경우 Null로 전달 Integer N ㄴㄴ goal 목표 수 Integer N ㄴㄴ limit 보상 제한 수 Integer N
응답 예제 {
"campaign_list" : [
{
"id" : "19" ,
"title" : "초대 코드 발급_행동_설치(초대 2, 수락 3, 제한 2)" ,
"rewards" : [
{
"reward_id" : 33 ,
"description" : "행동_설치(초대 2, 수락 3, 제한 2)" ,
"reward_type" : "action" ,
"action_type" : "cpi" ,
"cpa_code" : null ,
"goal" : 1 ,
"limit" : 2
}
]
}
],
"result_code" : 200 ,
"result_message" : "Success"
}
초대 코드 발급 받기 사용자는 캠페인에서 초대 코드를 발급받을 수 있습니다. 각 캠페인은 하나의 초대 코드만 발급할 수 있습니다. 초대자에게 보상을 지급하려면 초대자가 접속한 서버 ID를 전달해야 합니다.
API 요청 명세 Request URL 환경 URL 상용 https://promotion.qpyou.cn/ua/inviteCode/getCode
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/getCode
요청 방식 및 데이터 형식 항목 설명 HTTP Method POST
Content-Type application/json
필드명 설명 타입 필수여부 Authorization Bearer 인증을 통한 certificationKey
유효성 판단 String N
Request Body 필드명 설명 타입 필수여부 gameindex 게임 고유 번호 Integer Y campaign_id 초대 코드 캠페인 고유 번호 Integer Y player_id 모듈에 따라 vid 혹은 uid 중 1개 필요 - vid : 통합모듈인 경우 필수 - uid : 개별모듈인 경우 필수 String Y server_id 게임 서버 고유 ID String Y
호출 예제 curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/getCode" \
-H "Content-Type: application/json" \
-d '{
"gameindex" : 539,
"campaign_id": 19,
"player_id" : 12341234,
"server_id" : "kr"
}'
API 응답 명세 Response 필드명 설명 타입 필수여부 result_code 응답 코드 Integer Y result_message 응답 메시지 String Y invite_code 발급된 초대 코드 String Y
응답 예제 {
"invite_code" : "ESOJ0TOC" ,
"result_code" : 200 ,
"result_message" : "Success"
}
초대 코드 매칭하기 초대 코드를 입력하여 초대자와 수신자를 매칭 합니다. 보상 어뷰징을 방지하려면, 매칭 요청 전에 게임 서버에서 수락자 계정 정보가 유효한지 검증 후 요청하는 것을 권장합니다. 매칭 보상은 캠페인별로 최초 1회만 지급합니다.
API 요청 명세 Request URL 환경 URL 상용 https://promotion.qpyou.cn/ua/inviteCode/companion
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/companion
요청 방식 및 데이터 형식 항목 설명 HTTP Method POST
Content-Type application/json
필드명 설명 타입 필수여부 Authorization Bearer 인증을 통한 certificationKey
유효성 판단 String N
Request Body 필드명 설명 타입 필수여부 gameindex 게임 고유 번호 Integer Y invite_code 발급된 초대 코드 String Y player_id 모듈에 따라 vid 혹은 uid 중 1개 필요 - vid : 통합모듈인 경우 필수 - uid : 개별모듈인 경우 필수 String Y server_id 게임 서버 고유 ID String Y
호출 예제 curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/companion" \
-H "Content-Type: application/json" \
-d '{
"gameindex" : 539,
"invite_code" :"ESOJ0TOC",
"player_id" : 234234,
"server_id" : "kr"
}'
API 응답 명세 Response 필드명 설명 타입 필수여부 result_code 응답 코드 Integer Y result_message 응답 메시지 String Y detail 발급된 초대 코드 Array Y ㄴㄴmatched 매칭 여부 Boolean Y ㄴㄴreason 매칭 실패 사유 String Y
응답 예제 {
"detail" : {
"matched" : true ,
"reason" : "Both matching and rewards were successful"
},
"result_code" : 200 ,
"result_message" : "Success"
}
보상 현황 확인 하기 초대 코드의 보상 현황을 조회합니다.
API 요청 명세 Request URL 환경 URL 상용 https://promotion.qpyou.cn/ua/inviteCode/progress
Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/progress
요청 방식 및 데이터 형식 항목 설명 HTTP Method POST
Content-Type application/json
필드명 설명 타입 필수여부 Authorization Bearer 인증을 통한 certificationKey
유효성 판단 String N
Request Body 필드명 설명 타입 필수여부 gameindex 게임 고유 번호 Integer Y invite_code 발급된 초대 코드 String Y
호출 예제 curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/progress" \
-H "Content-Type: application/json" \
-d '{
"gameindex" : 539,
"invite_code" :"ESOJ0TOC"
}'
API 응답 명세 Response 필드명 설명 타입 필수여부 result_code 응답 코드 Integer Y result_message 응답 메시지 String Y progress_list 보상 진행 현황 리스트(보상 진행 이력 없을 시, 빈 배열로 전달) Array Y ㄴ reward_id 보상 ID Integer N ㄴ reward_type 보상 타입 action: 행동 보상 goal: 목표 수 달성 보상 String N ㄴ action_type 행동 타입 match: 매칭 cpi: 설치 cpa: 특정 행동 달성 String N ㄴ count 보상 지급 수 Integer N ㄴ max_reward 최대 보상 제한 수 Integer N ㄴ goal_progress 목표 달성 현황 보상 타입이 '목표 수 달성 보상'일때 사용 목표 수(goal) 만큼 달성 시 보상 지급 Integer N ㄴ goal 목표 수 Integer N ㄴ goal_achieved 목표 달성 수 Integer N
응답 예제 {
"progress_list" : [
{
"reward_id" : 19 ,
"reward_type" : "action" ,
"action_type" : "match" ,
"count" : 1 ,
"max_reward" : 1 ,
"goal_progress" : 0 ,
"goal_achieved" : 0
},
{
"reward_id" : 20 ,
"reward_type" : "goal" ,
"action_type" : "cpi" ,
"count" : 2 ,
"max_reward" : 2 ,
"goal_progress" : 1 ,
"goal" : 3 ,
"goal_achieved" : 2
}
],
"result_code" : 200 ,
"result_message" : "Success"
}