邀请码匹配¶

用户邀请是一个功能，允许用户发出邀请代码以邀请其他用户加入游戏，并因此从开发者那里获得奖励。用户邀请API是一个允许游戏发放邀请代码并匹配接受邀请的用户的API。

Warning

以下所有API的授权头并不是强制性的。然而，出于安全原因，建议使用Hive认证密钥并直接从游戏服务器调用API。

如何使用¶

在 Hive 控制台 > 促销 > 用户邀请 > 注册邀请活动 中，创建一个邀请代码发行类型的活动。
检索邀请活动信息，并将有效的活动 ID 存储在游戏服务器上。
在用户邀请页面，将接收到的邀请者信息和上述保存的活动 ID 作为调用参数传递给发行邀请代码。
将邀请者的信息（player_id 等）和邀请者收到的邀请代码作为调用参数传递，并发起匹配请求。
调用检查奖励状态，以在用户邀请页面上显示接收奖励的进度。

准备¶

要使用与邀请代码相关的 API，您需要准备以下项目。

用于授权头的 Hive 认证密钥：Hive 控制台 > 应用中心 > 项目管理 > 搜索应用后选择应用 > 游戏详情 > 基本信息 > Hive 认证密钥
server_id：Hive 控制台 > 应用中心 > 项目管理 > 搜索应用后选择应用 > 游戏详情 > 游戏服务器
邀请活动：通过在 Hive 控制台 > 推广 > 用户邀请 > 邀请活动注册 中注册创建活动来发布邀请代码类型。

活动信息检索¶

从 Hive 控制台检索创建的邀请活动信息。仅会提取活动中处于激活状态且可用的邀请活动信息。活动设置的奖励信息也将包含在响应中。

API 请求规范¶

请求 URL¶

环境	URL
商业	`https://promotion.qpyou.cn/ua/inviteCode/campaign`
沙盒	`https://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign`

请求方法和数据格式¶

项目	描述
HTTP 方法	`POST`
内容类型	`application/json`

标题¶

字段名称	描述	类型	必需
Authorization	通过 Bearer 认证对 `certificationKey` 的有效性进行检查	字符串	否

请求体¶

字段名称	描述	类型	必需
gameindex	唯一游戏编号	整数	Y

调用示例¶

curl -L -v -X POST --location "http://sandbox-promotion.qpyou.cn/ua/inviteCode/campaign" \
        -H "Content-Type: application/json" \
        -d '{
        "gameindex": 539
        }'

API 响应规范¶

响应¶

字段名称	描述	类型	必需
result_code	响应代码 200: 成功其他: 失败	整数	Y
result_message	响应消息	字符串	Y
campaign_list	邀请码活动列表	数组	Y
ㄴ id	促销活动ID	整数	N
ㄴ title	活动标题	字符串	N
ㄴ rewards	奖励列表	数组	N
ㄴㄴ reward_id	奖励ID	整数	N
ㄴㄴ description	奖励描述	字符串	N
ㄴㄴ reward_type	奖励类型 action: 行动奖励 goal: 目标达成奖励	字符串	N
ㄴㄴ action_type	行动类型 match: 匹配 cpi: 安装 cpa: 达成特定行动	字符串	N
ㄴㄴ cpa_code	CPA唯一编号如果行动类型为cpa，请提供有效值如果不是cpa，请提供Null	整数	N
ㄴㄴ goal	目标金额	整数	N
ㄴㄴ limit	奖励限制	整数	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 请求规范¶

请求 URL¶

环境	URL
生产	`https://promotion.qpyou.cn/ua/inviteCode/getCode`
沙盒	`https://sandbox-promotion.qpyou.cn/ua/inviteCode/getCode`

请求方法和数据格式¶

项目	描述
HTTP 方法	`POST`
内容类型	`application/json`

标题¶

字段名称	描述	类型	必需
Authorization	通过 Bearer 认证对 `certificationKey` 的有效性进行检查	字符串	否

请求体¶

字段名称	描述	类型	必需
gameindex	唯一游戏编号	整数	是
campaign_id	邀请码活动的唯一编号	整数	是
player_id	根据模块需要 vid 或 uid - vid: 集成模块所需 - uid: 单独模块所需	字符串	是
server_id	游戏服务器的唯一 ID	字符串	是

调用示例¶

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 响应规范¶

响应¶

字段名称	描述	类型	必需
result_code	响应代码 200: 成功其他: 失败	整数	Y
result_message	响应消息	字符串	Y
invite_code	发放的邀请代码	字符串	Y

响应示例¶

{
  "invite_code": "ESOJ0TOC",
  "result_code": 200,
  "result_message": "Success"
}

匹配邀请代码¶

输入邀请码以匹配邀请人和接受者。为了防止奖励滥用，建议在发起匹配请求之前验证接受者在游戏服务器上的账户信息。每个活动的匹配奖励仅发放一次。

API 请求规范¶

请求 URL¶

环境	URL
商业	`https://promotion.qpyou.cn/ua/inviteCode/companion`
沙盒	`https://sandbox-promotion.qpyou.cn/ua/inviteCode/companion`

请求方法和数据格式¶

项目	描述
HTTP 方法	`POST`
内容类型	`application/json`

标题¶

字段名称	描述	类型	必需
Authorization	通过 Bearer 认证对 `certificationKey` 的有效性进行检查	字符串	否

请求体¶

字段名称	描述	类型	必需
gameindex	唯一的游戏编号	整数	是
invite_code	发放的邀请码	字符串	是
player_id	根据模块需要提供vid或uid - vid: 集成模块必需 - uid: 单独模块必需	字符串	是
server_id	游戏服务器的唯一ID	字符串	是

调用示例¶

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 响应规范¶

响应¶

字段名称	描述	类型	必需
result_code	响应代码 200: 成功其他: 失败	整数	Y
result_message	响应消息	字符串	Y
detail	发出的邀请代码	数组	Y
ㄴㄴmatched	匹配状态	布尔值	Y
ㄴㄴreason	匹配失败的原因	字符串	Y

响应示例¶

{
  "detail": {
    "matched": true,
    "reason": "Both matching and rewards were successful"
  },
  "result_code": 200,
  "result_message": "Success"
}

检查奖励状态¶

检查邀请码的奖励状态。

API 请求规范¶

请求 URL¶

环境	URL
生产	`https://promotion.qpyou.cn/ua/inviteCode/progress`
沙盒	`https://sandbox-promotion.qpyou.cn/ua/inviteCode/progress`

请求方法和数据格式¶

项目	描述
HTTP 方法	`POST`
内容类型	`application/json`

标题¶

字段名称	描述	类型	必需
Authorization	通过 Bearer 认证对 `certificationKey` 的有效性进行检查	字符串	否

请求体¶

字段名称	描述	类型	必需
gameindex	唯一游戏编号	整数	是
invite_code	发放的邀请码	字符串	是

调用示例¶

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 响应规范¶

响应¶

字段名称	描述	类型	必需
result_code	响应代码 200: 成功其他: 失败	整数	Y
result_message	响应消息	字符串	Y
progress_list	奖励进度状态列表（如果没有奖励进度历史，则返回空数组）	数组	Y
ㄴ reward_id	奖励ID	整数	N
ㄴ reward_type	奖励类型 action: 行动奖励 goal: 目标达成奖励	字符串	N
ㄴ action_type	行动类型 match: 匹配 cpi: 安装 cpa: 达成特定行动	字符串	N
ㄴ count	发放的奖励数量	整数	N
ㄴ max_reward	最大奖励限制	整数	N
ㄴ goal_progress	目标达成状态当奖励类型为“目标达成奖励”时使用达成目标时给予奖励	整数	N
ㄴ goal	目标数量当奖励类型为“目标达成奖励”时使用	整数	N
ㄴ goal_achieved	达成的目标数量当奖励类型为“目标达成奖励”时使用	整数	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"
}