邀請碼基於匹配¶

用戶邀請是一項功能，允許用戶發出邀請碼以邀請其他用戶參加遊戲，並因此從開發者那裡獲得獎勵。用戶邀請 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`

標題¶

欄位名稱	描述	類型	是否必填
授權	通過 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`

標題¶

字段名稱	描述	類型	是否必填
授權	通過 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`

標題¶

欄位名稱	描述	類型	必填
授權	透過 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` 的有效性	字串	N

請求主體¶

欄位名稱	描述	類型	必需
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: 成功其他: 失敗	整數	是
result_message	回應訊息	字串	是
progress_list	獎勵進度狀態列表（如果沒有獎勵進度歷史，則返回空數組）	陣列	是
ㄴ reward_id	獎勵ID	整數	否
ㄴ reward_type	獎勵類型 action: 行動獎勵 goal: 目標達成獎勵	字串	否
ㄴ action_type	行動類型 match: 匹配 cpi: 安裝 cpa: 達成特定行動	字串	否
ㄴ count	獎勵數量	整數	否
ㄴ max_reward	最大獎勵限制	整數	否
ㄴ goal_progress	目標達成狀態當獎勵類型為「目標達成獎勵」時使用當達成目標（goal）時給予獎勵	整數	否
ㄴ goal	目標數量當獎勵類型為「目標達成獎勵」時使用	整數	否
ㄴ goal_achieved	已達成的目標數量當獎勵類型為「目標達成獎勵」時使用	整數	否

回應範例¶

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