Invitation Code Based Matching User invitation is a feature that allows a user to issue an invitation code to invite other users to the game and receive rewards from the developer for doing so. The user invitation API is an API that allows the game to issue invitation codes and match users who have accepted the invitation.
Warning The Authorization Header is not mandatory for all APIs below. However, for security reasons, it is recommended to use the Hive authentication key and call the API directly from the game server.
How to use In the Hive console > Promotion > User Invitation > Register Invitation Campaign , create a campaign with the invitation code issuance type. Retrieve the invitation campaign information and store the valid campaign ID on the game server. On the user invitation page, pass the inviter information received and the campaign ID saved above as call parameters to issue the invitation code . Pass the inviter's information (player_id, etc.) and the invitation code received by the inviter as call parameters and make a matching request . Call check reward status to display the progress for receiving rewards on the user invitation page. Preparation To use the invitation code-related API, you need to prepare the following items.
Hive authentication key to be used in the Authorization Header: Hive Console > App Center > Project Management > Select App after searching for the app > Game Details > Basic Information > Hive Authentication Key server_id: Hive Console > App Center > Project Management > Select App after searching for the app > Game Details > Game Server Invitation Campaign: Issue invitation code type by registering create campaign in Hive Console > Promotion > User Invitation > Invitation Campaign Registration Campaign Information Retrieval Retrieving invitation campaign information created in the Hive console. Only active and available invitation campaign information will be fetched. The reward information set for the campaign will also be included in the response.
API Request Specification Request URL Environment URL Commercial https://promotion.qpyou.cn/ua/inviteCode/campaign Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign
Item Description HTTP Method POST Content-Type application/json
Field Name Description Type Required Authorization Validity check of certificationKey through Bearer authentication String N
Request Body Field Name Description Type Required gameindex Unique game number Integer Y
Call Example -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign" \
-H "Content-Type: application/json" \
-d '{
"gameindex": 539
}'
API Response Specification Response Field Name Description Type Required result_code Response code 200: Success Otherwise: Failure Integer Y result_message Response message String Y campaign_list Invitation code campaign list Array Y ㄴ id Promotion campaign ID Integer N ㄴ title Campaign title String N ㄴ rewards Reward list Array N ㄴㄴ reward_id Reward ID Integer N ㄴㄴ description Reward description String N ㄴㄴ reward_type Reward type action: Action reward goal: Goal achievement reward String N ㄴㄴ action_type Action type match: Matching cpi: Installation cpa: Achieving specific action String N ㄴㄴ cpa_code CPA unique number Provide a valid value if the action type is cpa Provide Null if not cpa Integer N ㄴㄴ goal Goal amount Integer N ㄴㄴ limit Reward limit Integer N
Response Example {
"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"
}
Get Invite Code Users can receive invitation codes in the campaign. Each campaign can issue only one invitation code. To reward the inviter, the server ID that the inviter accessed must be provided.
API Request Specification Request URL Environment URL Production https://promotion.qpyou.cn/ua/inviteCode/getCode Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/getCode
Item Description HTTP Method POST Content-Type application/json
Field Name Description Type Required Authorization Validity check of certificationKey through Bearer authentication String N
Request Body Field Name Description Type Required gameindex Unique game number Integer Y campaign_id Unique number for the invitation code campaign Integer Y player_id Requires either vid or uid depending on the module String Y server_id Unique ID for the game server String Y
Call Example -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 Specification Response Field Name Description Type Required result_code Response code 200: Success Others: Failure Integer Y result_message Response message String Y invite_code Issued invitation code String Y
Response Example {
"invite_code" : "ESOJ0TOC" ,
"result_code" : 200 ,
"result_message" : "Success"
}
Matching Invitation Codes Enter the invitation code to match the inviter and the recipient. To prevent reward abuse, it is recommended to verify the acceptor's account information on the game server before making the matching request. Matching rewards are given only once per campaign.
API Request Specification Request URL Environment URL Commercial https://promotion.qpyou.cn/ua/inviteCode/companion Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/companion
Item Description HTTP Method POST Content-Type application/json
Field Name Description Type Required Authorization Validity check of certificationKey through Bearer authentication String N
Request Body Field Name Description Type Required gameindex Unique game number Integer Y invite_code Issued invitation code String Y player_id One of vid or uid is required depending on the module String Y server_id Unique ID of the game server String Y
Call Example -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 Specification Response Field Name Description Type Required result_code Response code 200: Success Others: Failure Integer Y result_message Response message String Y detail Issued invitation code Array Y ㄴㄴmatched Matching status Boolean Y ㄴㄴreason Reason for matching failure String Y
Response Example {
"detail" : {
"matched" : true ,
"reason" : "Both matching and rewards were successful"
},
"result_code" : 200 ,
"result_message" : "Success"
}
Check Reward Status Checking the reward status of the invitation code.
API Request Specification Request URL Environment URL Production https://promotion.qpyou.cn/ua/inviteCode/progress Sandbox https://sandbox-promotion.qpyou.cn/ua/inviteCode/progress
Item Description HTTP Method POST Content-Type application/json
Field Name Description Type Required Authorization Validity check of certificationKey through Bearer authentication String N
Request Body Field Name Description Type Required gameindex Unique game number Integer Y invite_code Issued invitation code String Y
Call Example -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 Specification Response Field Name Description Type Required result_code Response code 200: Success Others: Failure Integer Y result_message Response message String Y progress_list List of reward progress status (if there is no reward progress history, an empty array is returned) Array Y ㄴ reward_id Reward ID Integer N ㄴ reward_type Reward type action: Action reward goal: Goal achievement reward String N ㄴ action_type Action type match: Matching cpi: Installation cpa: Achieving specific action String N ㄴ count Number of rewards given Integer N ㄴ max_reward Maximum reward limit Integer N ㄴ goal_progress Goal achievement status Used when the reward type is 'goal achievement reward' Reward is given when the goal (goal) is achieved Integer N ㄴ goal Goal count Used when the reward type is 'goal achievement reward' Integer N ㄴ goal_achieved Number of goals achieved Used when the reward type is 'goal achievement reward' Integer N
Response Example {
"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"
}