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`

Request Method and Data Format¶

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¶

curl -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`

Request Method and Data Format¶

Item	Description
HTTP Method	`POST`
Content-Type	`application/json`

Header¶

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 - vid: required for integrated module - uid: required for individual module	String	Y
server_id	Unique ID for the game server	String	Y

Call Example¶

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 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`

Request Method and Data Format¶

Item	Description
HTTP Method	`POST`
Content-Type	`application/json`

Header¶

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 - vid: Required for integrated module - uid: Required for individual module	String	Y
server_id	Unique ID of the game server	String	Y

Call Example¶

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 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`

Request Method and Data Format¶

Item	Description
HTTP Method	`POST`
Content-Type	`application/json`

Header¶

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¶

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 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"
}