用户参与 (UE, 深度链接)
用戶參與 (UE) 提供帶有優惠券的深度鏈接功能，允許通過簡單點擊鏈接邀請遊戲用戶到達遊戲中的特定位置或事件頁面，或直接獲得獎勵。
在 Hive SDK 中，您希望通过方案 URL 执行的操作称为用户参与操作。当游戏执行给定 URL 中指定的操作时，Hive 以用户参与事件的形式向游戏发出请求。
什麼是用戶參與？¶
UE是一個從應用程式內部和外部執行請求的服務，並執行以下功能：
- 透過深層連結或推播通知從應用程式外部執行方案 URL。
- 透過互動從應用程式內部執行方案 URL。
- 使用 Hive SDK v4.4.0 及更高版本，
- 透過用戶獲取創建的 QR 碼和連結等外部路徑將訪問歷史發送到遊戲應用程式以請求獎勵。
- 確保遊戲客戶端實現
setEngagementReadyAPI，並在 Hive SDK 模組可用時發送請求，以執行 UE 的功能來處理 CPI 獎勵等。
如何指示方案 URL¶
Scheme URL 是一種表達 UE 行動的格式。它指示在 Scheme URL 中定義了什麼行動，以及它適用於誰。使用 Hive 的 Scheme URL 遵循一種稱為統一資源標識符 (URI) 的標準格式，並由服務字段和公共字段組成。
- 標準格式: {scheme}://{host}/{path}?{query}
- Hive 格式: {scheme}://{host}/{api}?{parameters}
- 服務欄位: {scheme}://{host} | 通用欄位: /{api}?{parameters}
Note
Hive 格式 表示在 Hive SDK 上处理的事件，并包含给定的 {api}，如 常见字段 部分所示。因此，Hive 格式的常见字段由 /{api}?{parameters} 组成，而不是标准格式的 /{path}?{query}。有关包含在 Hive 格式 中的 {api} 的列表，请参见 常见字段。
在遊戲中使用方案 URL¶
除了使用 UE 進行優惠券深度鏈接外，如果您需要在遊戲中移動到特定位置（例如，地下城、禮品盒、商店等）以達到促銷目的，請確保在遊戲中定義路徑，並提供方案 URL。此方案 URL 會轉換為 Hive 控制台上的登陸 URL，然後傳遞給用戶。
有關遊戲中方案 URL 的更多信息，請參見 如果方案 URL 的主機是遊戲。
服務領域¶
方案 URL 的服務欄位為 {scheme}://{host}，這表示深層鏈接傳遞到 Hive SDK 的路徑，由 scheme 和 host 組成。
方案¶
有三條路徑可以將 URL 傳遞給應用程式：
推送
無論目標應用程式是否正在運行，接收該方案 URL 的用戶都會收到一條包含該方案 URL 的推送消息。當接收者點擊該消息時，推送方案 URL 將發送到 Hive 客戶端，然後 Hive 客戶端處理該 URL。
- 例如，
深度連結
如果用戶通過外部方式（例如短信和網頁瀏覽器）點擊一個URL，並且該URL的scheme字段填寫了用戶設備上特定遊戲的AppID，則該遊戲將被執行，並且該URL將被傳遞到Hive SDK。如果遊戲應用未安裝，則將轉到安裝頁面。
- 例如，com.com2us.example://{host}/{path}?{query}
使用深度链接方案时，用户跟随的状态取决于游戏安装的状态。
1. <b>如果遊戲已安裝</b>
當用戶點擊深層連結時，用戶首先檢查遊戲提示，然後進入遊戲。
{width="700px"}
2. <b>如果遊戲未安裝</b>
當用戶點擊消息中的連結時，會通知用戶在遊戲安裝後可獲得獎勵。由於遊戲未安裝，將轉移到下載市場（Google Play 商店 / Apple App Store）。
{width="700px"}
Interwork
如果用户在应用程序运行时触摸Hive SDK的促销屏幕（横幅、通知等）的特定链接URL，并且该URL的方案字段为“interwork”，则该URL将被传递给Hive SDK。
- 例如，interwork://{host}/{path}?{query}
您可以使用 processURI API 直接从游戏向 Hive SDK 发送 URL 来调用处理互操作方案的请求。
主機¶
主機 指定了誰負責請求的行動：
- 遊戲: 遊戲負責的行動
- 蜂巢: Hive SDK 負責的行動
常見欄位¶
Scheme URL 的常見字段是 /{api}/{parameters}，這表示要處理的動作，包括所需的信息：
API 澄清了通過 URL 應採取的行動。根據主機可以採取以下行動：
如果方案 URL 的主機是¶
請注意，可用的 API 取決於身份驗證版本，v4 或 v1。
| API | 實作 | Auth v4 | Auth v1 |
|---|---|---|---|
| authlogin auth/login | 會員登入 (訪客 -> 驗證過的帳號) | X | O |
| socialinquiry social/inquiry | 訪問 1:1 詢問頁面 | O | O |
| promotionshow promotion/show | 推廣自定義視圖曝光 | O | O |
| promotioncoupon promotion/coupon | 處理已使用的推廣優惠券 | O | O |
| iappromote | 項目購買預約 (Hive SDK v4.5.0 及更高版本與 IAP v4) | O | O |
| iappurchase | 現場橫幅上的項目購買 (Hive SDK v4.5.0 及更高版本與 IAP v4) 實作 iappurchase 時，setEngagementReady() 會自動變為 false。購買後，您需要將 setEngagementReady() 設置為 true | O | O |
| social/myinquiry | 訪問我的詢問頁面 | O | O |
| social/profile | 訪問個人資料頁面 | O | O |
Hive SDK 在與 UE 相關的過程之前和之後通過 EngagementListener 接收通知。遊戲可能需要進行一些工作，例如在需要時暫停遊戲。
有關 iappromote 和 iappurchase 的更多資訊，請參閱以下內容。
iappromote
IAP v4 與 Hive SDK v4.5.0 及以後版本支持此功能。它為用戶在執行遊戲之前提供購買預留。此功能與 iOS 11 提供的促銷 IAP 功能相同，並支持基於 Android 的環境。iappromote 可用於事件頁面、推送服務和消息。
- 當用戶通過事件頁面點擊方案 URL、推送服務和消息時，通過執行遊戲獲取購買數據。
- 調用 iappromote 方案並接收
EngagementEventType.IAP\_PROMOTE作為結果數據。使用結果值，實現 checkPromotePurchase API 以獲取市場 PID。在實現購買 API 時，可以使用作為參考的市場 PID 繼續購買過程。 - iappromote 在 iOS 和 Android 上均可用。
- 方案 URL 的結構：[AppID/push/interwork]://hive/iappromote?marketpid=[marketpid]
- 例如，
- interwork://hive/iappromote?marketpid=com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs02
- 將紅色部分替換為與預留購買相關的市場 PID。
iappurchase
IAP v4 與 Hive SDK v4.5.0 及更高版本支持此功能。您可以通過在方案 URL 中使用 iappurchase 來即時銷售項目。
* 如果您调用 iappurchase 方案，则会实现购买逻辑。因此，请确保在执行该方案之前初始化市场并获取商店信息。这意味着，在将 `setEngagementReady` 的状态更改为 true 之前，必须实现 `marketConnect API` 和 `getProductInfo API`。
* 由于游戏在购买后执行逻辑，因此会暂停参与操作（`setEngagementReady` 会自动变为 false）。
* 购买完成后，将 `setEngagementReady` 的状态更改为 true 以继续操作。
* 方案 URL 的结构：[AppID/push/interwork]://hive/iappurchase?marketpid=[marketpid]
* 例如，
+ interwork://hive/iappurchase?marketpid=com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01
+ 将红色部分替换为与保留购买相关的市场 PID。
使用 Spot Banner 同步 iappurchase
如果您想通过使用 iappurchase 方案来销售商品，请利用 Spot Banner。查看使用 Spot Banner 的指南
- 在遊戲中設置一個特定位置或時間的廣告橫幅 ID，以鼓勵用戶購買物品。
- 調用廣告橫幅 ID。當用戶點擊廣告橫幅時，實施互動方案。註冊的 EngagementListener 將發送互動的運行狀態。
- 如果您調用互動方案，則會實施購買邏輯。因此，請確保在執行方案之前初始化市場並獲取商店信息。這意味著在調用廣告橫幅之前，實施
marketConnect API和getProductInfo API。 - 由於遊戲在購買後執行邏輯，因此會暫停參與行動（
setEngagementReady自動變為 false）。 - 購買完成後，將
setEngagementReady的狀態更改為 true 以繼續行動。 - 在 Hive 控制台 > 推廣 > 活動設置 > 廣告橫幅 中輸入廣告橫幅 ID，並在內部鏈接中插入方案 URL。請求如何向業務 PM 註冊廣告橫幅。
- 例如，
- interwork://hive/iappurchase?marketpid=com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01
- 將紅色部分替換為與預留購買相關的市場 PID。
- 當您在控制台上註冊橫幅時，請在您的遊戲中測試購買。
如果方案 URL 的主機是遊戲¶
在這種情況下，遊戲必須執行請求的操作。Hive SDK 正在處理方案 URL，然後通過 EngagementListener 以 JSONObject 格式發送結果。結果分為 scheme、api 和 param 鍵。確保遊戲在收到值後在適當的時間執行相關操作。
- 例如，將物品放入郵箱
- URL 方案 : com.com2us.example://game/postboxadditem?item_id=123456&item_title=item01
-
來自 Hive SDK 的 JSONObject 結果
有關如何實現用戶參與的更多細節，請參見 實現用戶參與 > 聲明和註冊全局回調 的示例代碼。
專案設定¶
在遊戲應用中使用UE，需在構建應用之前由操作系統設置。
Android 設定¶
將 launchMode 方法設置為 singleTask 或 singleTop。該方法是 AndroidManifest.xml 文件中的主活動項目之一。
//<application
android:hardwareAccelerated="true"
android:icon="@drawable/app_icon"
android:label="@string/app_name"
android:isGame="true">
<activity
android:label="@string/app_name"
android:name="com.hive.sample.MainActivity"
android:screenOrientation="sensor"
android:launchMode="singleTask"
...
iOS 設定¶
- 在 Xcode TARGETS 列表中選擇您想要開發的應用程序的版本。
- 選擇 Info 標籤。
- 在 URL Types 部分添加 Additional url type properties 項目，以在 Bundle Identifier 和 URL Schemes 欄位中輸入 AppID。
實施用戶參與¶
宣告和註冊全域回呼¶
聲明並註冊全域回調以應用 UE。聲明和註冊的方式取決於 Hive SDK 的版本。
Note
- 從 Hive SDK v4.5.0 及以後版本，全球回調的聲明和註冊是通過 Promotion 類的處理程序註冊 API 完成的。
- 互動處理程序格式和枚舉值從 Hive SDK v4.5.0 及以後版本中已更改。
您必須使用**Promotion**類別的處理程序註冊API註冊全域回呼。以下是範例代碼。
API 參考: hive.Promotion.setEngagementListener
using hive;
Promotion.setEngagementListener((ResultAPI result, EngagementEventType engagementEventType, EngagementEventState engagementEventState, JSONObject param) => {
switch (engagementEventType) {
case EngagementEventType.EVENT_TYPE:
switch (engagementEventState) {
case EngagementEventState.BEGIN:
// 所有的参与操作都已执行
break;
case EngagementEventState.FINISH:
// 所有的参与操作都已完成
break;
}
break;
case EngagementEventType.AUTH_LOGIN_VIEW:
switch (engagementEventState) {
case EngagementEventState.START:
// 开始会员登录页面曝光请求
break;
case EngagementEventState.END:
// 会员登录完成（在登录完成/窗口关闭后发送）
break;
}
break;
case EngagementEventType.SOCIAL_INQUIRY_VIEW:
switch (engagementEventState) {
case EngagementEventState.START:
// 开始1:1咨询页面曝光请求
break;
case EngagementEventState.END:
// 1:1咨询页面曝光完成（在1:1咨询窗口关闭后发送）
break;
}
break;
case EngagementEventType.PROMOTION_VIEW:
switch (engagementEventState) {
case EngagementEventState.START:
// 开始促销视图印象请求
break;
case EngagementEventState.END:
// 促销视图曝光完成（在促销窗口关闭后发送）
break;
}
break;
caseEngagementEventType.COUPON:
switch (engagementEventState) {
case EngagementEventState.START:
// 开始优惠券消费请求
break;
case EngagementEventState.END:
// 完成优惠券消费请求并发送响应
break;
}
break;
case EngagementEventType.EVENT:
// 如果主機是遊戲，發送JSONObject結果值
String api = "";
String param = "";
param.GetField(ref api, "api");
param.GetField(ref param, "param");
// 檢查 api 和參數解析結果，根據 Hive SDK 版本（根據 Hive SDK C# JSONObject 版本的差異）
// 例如） interwork://game/openurl?rurl=https://www.withhive.com
//在 Hive SDK 4.16.2 下
// 当输出到 API 调试控制台时: \/openurl
// ( api.Equals("\\/openurl"); )
// 参数调试控制台输出: rurl=https:\/\/www.withhive.com
// Hive SDK 4.16.2 或更高版本
// 输出到 API 调试控制台时: /openurl
// (api.Equals("/openurl"); )
// 参数调试控制台输出: rurl=https://www.withhive.com
// TODO: 根據 api 和參數值執行以下操作
break;
case EngagementEventType.IAP_UPDATED:
switch (engagementEventState) {
case EngagementEventState.EVENT_START:
// 信號接受，因為購買歷史已更改（調用 Restore() 方法）
break;
case EngagementEventState.EVENT_END:
// 信號接受，因為購買歷史已更改（調用 Restore() 方法）
String type = "";
param.getField(ref type, "type");
if (type == "subscription") {
// TODO: 恢复订阅产品
IAPV4.restoreSubscription((ResultAPI result, List <hive.IAPV4.IAPV4Receipt> receiptList) => {
if (!result.isSuccess()) {
return;
}
// TODO: 使用收到的 receiptList 请求收据验证
});
return;
}
// TODO: 恢复可消费商品
IAPV4.restore((ResultAPI result, List <hive.IAPV4.IAPV4Receipt> receiptList) => {
if (!result.isSuccess()) {
return;
}
// TODO: 使用收到的 receiptList 请求收据验证
});
break;
}
break;
case EngagementEventType.IAP_PROMOTE:
switch (engagementEventState) {
case EngagementEventState.START:
// Convey whether IAP Promote data exists
break;
case EngagementEventState.END:
if (!result.isSuccess()) {
return;
}
// 由於存在 IAP Promote 數據，marketPid 是通過 checkPromote API 獲取的。
IAPV4.checkPromotePurchase((ResultAPI promoteResult, String marketPid) => {
if (!promoteResult.isSuccess()) {
return;
}
// TODO: 請求購買已接收的 marketPid 項目
IAPV4.purchase(marketPid, null, (ResultAPI purchaseResult, hive.IAPV4.IAPV4Receipt receipt) => {
if (!purchaseResult.isSuccess()) {
return;
}
// TODO: 請求收據驗證與接收的收據
});
});
break;
}
break;
case EngagementEventType.IAP_PURCHASE:
switch (engagementEventState) {
case EngagementEventState.START:
// 透過 IAPPurchase 架構顯示購買項目的彈出窗口。
break;
case EngagementEventState.END:
// 是否成功購買請求的項目通過 IAPPurchase 架構進行傳達。
if (!result.isSuccess()) {
return;
}
String receipt = "";
param.GetField(ref receipt, "iapV4Receipt");
break;
}
break;
case EngagementEventType.SOCIAL_MY_INQUIRY:
switch (engagementEventState) {
case EngagementEventState.START:
// 開始我的詢問頁面曝光請求
break;
case EngagementEventState.END:
// 我的詢問頁面已被曝光（在我的詢問窗口關閉後交付）
break;
}
break;
case EngagementEventType.SOCIAL_PROFILE:
switch (engagementEventState) {
case EngagementEventState.START:
// Initiate profile page exposure request
break;
case EngagementEventState.END:
// Profile page exposure completed (delivered after closing the profile window)
break;
}
break;
}
});
#include "HivePromotion.h"
FHivePromotion::SetEngagementDelegate(FHivePromotionOnEngagementDelegate::CreateLambda([this](const FHiveResultAPI& Result, const EHiveEngagementEventType& EngagementEventType, const EHiveEngagementEventState& EngagementEventState, TSharedPtr<FJsonObject> Param) {
switch (EngagementEventType) {
case EHiveEngagementEventType::EVENT_TYPE:
switch (EngagementEventState) {
case EHiveEngagementEventState::BEGIN:
// 所有的參與行動都已執行
break;
case EHiveEngagementEventState::FINISH:
// 所有的參與行動都已完成
break;
}
break;
case EHiveEngagementEventType::AUTH_LOGIN_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Hive 會員登入頁面顯示請求開始
break;
case EHiveEngagementEventState::EVENT_END:
// Hive 會員登入執行完成（在登入完成/視窗關閉執行後通過）
break;
}
break;
case EHiveEngagementEventType::SOCIAL_INQUIRY_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 1:1 諮詢頁面曝光請求開始
break;
case EHiveEngagementEventState::EVENT_END:
// 1:1 諮詢頁面曝光完成（關閉 1:1 諮詢窗口後）
break;
}
break;
case EHiveEngagementEventType::PROMOTION_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 促銷視圖曝光請求開始
break;
case EHiveEngagementEventState::EVENT_END:
// 促銷視圖曝光完成（在關閉促銷窗口後交付）
break;
}
break;
case EHiveEngagementEventType::COUPON:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 開始優惠券消費請求
break;
case EHiveEngagementEventState::EVENT_END:
// 完成優惠券消費請求並發送回應
break;
}
break;
case EHiveEngagementEventType::EVENT:
// 如果主機是遊戲，傳遞參數結果值（鍵： "api", "param"）
// TODO: 根據 api 和 param 值執行邏輯處理
break;
case EHiveEngagementEventType::IAP_UPDATED:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
//Signal to receive the purchase information as it has changed
break;
case EHiveEngagementEventState::EVENT_END:
// 購買歷史已更改，因此發出信號以接收它
FString TypeValue;
if (Param.IsValid() && Param->TryGetStringField(TEXT("type"), TypeValue)) {
if (TypeValue == TEXT("subscription")) {
// TODO: 恢復訂閱產品
} else {
// TODO: 恢復消耗品產品
}
}
break;
}
break;
case EHiveEngagementEventType::IAP_PROMOTE:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 傳遞 IAP 推廣數據存在
break;
case EHiveEngagementEventState::EVENT_END:
if (!Result.IsSuccess()) {
return;
}
// 由於存在 IAP 推廣數據，我們通過檢查推廣 API 接收 marketPid
FHiveIAPV4::CheckPromotePurchase(FHiveIAPV4OnCheckPromotePurchaseDelegate::CreateLambda([=](const FHiveResultAPI& PromoteResult, const FString& MarketPid) {
if (!PromoteResult.IsSuccess()) {
return;
}
// TODO: 請求購買傳入的 MarketPid 的項目
FString IapPayload = TEXT("");
FHiveIAPV4::Purchase(MarketPid, IapPayload, FHiveIAPV4OnPurchaseDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveIAPV4Receipt& Receipt) {
// TODO: 使用接收到的收據請求收據驗證
}));
}));
break;
}
break;
case EHiveEngagementEventType::IAP_PURCHASE:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 顯示接收到的項目的購買彈出窗口，使用 IAPPurchase 模式
break;
case EHiveEngagementEventState::EVENT_END:
// 請求的項目的購買是否成功通過 IAPPurchase 模式傳輸
if (!Result.IsSuccess) {
return;
}
FString ReceiptValue;
if (Param.IsValid() && Param->TryGetStringField(TEXT("iapV4Receipt"), ReceiptValue)) {
// 发送购买收据
// TODO: 验证收据并处理物品付款
}
break;
}
break;
case EHiveEngagementEventType::SOCIAL_MY_INQUIRY:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 開始顯示我的詢問頁面請求
break;
case EHiveEngagementEventState::EVENT_END:
// 我的詢問頁面顯示完成（在關閉我的詢問窗口後傳遞）
break;
}
break;
case EHiveEngagementEventType::SOCIAL_PROFILE:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 開始請求顯示我的詢問頁面
break;
case EHiveEngagementEventState::EVENT_END:
// 完成顯示我的詢問頁面（在關閉我的詢問窗口後發送）
break;
}
break;
}
}));
API 參考: Promotion::setEngagementHandler
#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;
Promotion::setEngagementHandler([ = ](ResultAPI
const & result, EngagementEventType engagementEventType, EngagementEventState engagementEventState, picojson::value
const & param) {
switch (engagementEventType) {
case EngagementEventType::EVENT_TYPE:
switch (engagementEventState) {
case EngagementEventState::BEGIN:
// 所有的参与动作都已执行
break;
case EngagementEventState::FINISH:
// 所有的参与动作都已完成
break;
}
break;
case EngagementEventType::AUTH_LOGIN_VIEW:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 开始会员登录页面曝光请求
break;
case EngagementEventState::EVENT_END:
// 会员登录完成（在登录完成/窗口关闭后发送）
break;
}
break;
case EngagementEventType::SOCIAL_INQUIRY_VIEW:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 开始1:1咨询页面曝光请求
break;
case EngagementEventState::EVENT_END:
// 1:1咨询页面曝光完成（在1:1咨询窗口关闭后发送）
break;
}
break;
case EngagementEventType::PROMOTION_VIEW:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 开始促销视图印象请求
break;
case EngagementEventState::EVENT_END:
// 促销视图曝光完成（在促销窗口关闭后发送）
break;
}
break;
case EngagementEventType::COUPON:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 开始优惠券消费请求
break;
case EngagementEventState::EVENT_END:
// 完成优惠券消费请求并发送响应
break;
}
break;
case EngagementEventType::EVENT:
// 如果主机是游戏，发送JSONObject结果值
if (param == null) {
return;
}
string api = param.get("api").to_str();
string param = param.get("param").to_str();
// TODO: 根据api和param值执行以下操作
break;
case EngagementEventType::IAP_UPDATED:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// Signal to receive since purchase details have changed
break;
case EngagementEventState::EVENT_END:
// Signal to receive since purchase details have changed
string type = param.get("type").to_str();
if (type != null, type == "subscription") {
// TODO: restore subscription product
IAPV4::restoreSubscription([ = ](ResultApi
const & result, vector < reference_wrapper < IAPV4Receipt >> receiptList) {
if (!result.isSuccess()) {
return;
}
// TODO: Request receipt verification using the received receiptList
});
return;
}
// TODO: 恢复可消费商品
IAPV4::restore([ = ](ResultAPI
const & result, vector < reference_wrapper < IAPV4Receipt >> receiptList) {
if (!result.isSuccess()) {
return;
}
// TODO: 使用收到的 receiptList 请求收据验证
});
break;
}
break;
case EngagementEventType::IAP_PROMOTE:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// Convey whether IAP Promote data exists
break;
case EngagementEventState::EVENT_END:
if (!result.isSuccess()) {
return;
}
// 由於存在 IAP Promote 數據，marketPid 是通過檢查 Promote API 獲得的。
IAPV4::checkPromotePurchase([ = ](ResultApi
const & promoteResult, string marketPid) {
if (!promoteResult.isSuccess()) {
return;
}
// TODO: 請求購買已交付的市場 Pid 項目
IAPV4::purchase(marketPid, "", [ = ](ResultApi
const & purchaseResult, IAPV4Receipt
const * receipt) {
if (!purchaseResult.isSuccess()) {
return;
}
// TODO: 使用收到的收據請求收據驗證
});
});
break;
}
break;
case EngagementEventType::IAP_PURCHASE:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 透過 IAPPurchase 架構顯示購買項目的彈出窗口。
break;
case hive::EngagementEventState::EVENT_END:
// 是否成功購買請求的項目通過 IAPPurchase 架構進行傳達。
if (result.isSucces()) {
return;
}
picojson::value receiptJson = param.get("iapV4Receipt");
shared_ptr receipt = IAPV4Receipt::create(receiptJson);
break;
}
break;
case EngagementEventType::SOCIAL_MY_INQUIRY:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 開始我的詢問頁面曝光請求
break;
case EngagementEventState::EVENT_END:
// 我的詢問頁面已曝光（在我的詢問視窗關閉後交付）
break;
}
break;
case EngagementEventType::SOCIAL_PROFILE:
switch (engagementEventState) {
case EngagementEventState::EVENT_START:
// 發起個人資料頁面曝光請求
break;
case EngagementEventState::EVENT_END:
// 個人資料頁面曝光完成（在關閉個人資料窗口後交付）
break;
}
break;
}
});
API 參考: setEngagementListener
import com.hive.IAPV4
import com.hive.Promotion
import com.hive.ResultAPI
Promotion.setEngagementListener(object: Promotion.EngagementListener {
override fun onEngagement(
result: ResultAPI,
engagementEventType: Promotion.EngagementEventType,
engagementEventState: Promotion.EngagementEventState,
param: JSONObject ?
) {
// 根據干預類型從 Hive SDK 分支的代碼
when(engagementEventType) {
Promotion.EngagementEventType.EVENT_TYPE -> when(engagementEventState) {
Promotion.EngagementEventState.BEGIN -> {
// 所有的參與行動都已執行
}
Promotion.EngagementEventState.FINISH -> {
// 所有的參與行動都已完成
}
else -> {}
}
Promotion.EngagementEventType.AUTH_LOGIN_VIEW -> when(engagementEventState) {
Promotion.EngagementEventState.START -> {
// 開始會員登錄頁面曝光請求
}
Promotion.EngagementEventState.END -> {
// 會員登錄完成（登錄完成/窗口關閉後發送）
}
else -> {}
}
Promotion.EngagementEventType.SOCIAL_INQUIRY_VIEW -> when(engagementEventState) {
Promotion.EngagementEventState.START -> {
// 開始 1:1 查詢頁面曝光請求
}
Promotion.EngagementEventState.END -> {
// 1:1 查詢頁面曝光完成（在 1:1 查詢窗口關閉後發送）
}
else -> {}
}
Promotion.EngagementEventType.PROMOTION_VIEW -> when(engagementEventState) {
Promotion.EngagementEventState.START -> {
// 開始促銷視圖印象請求
}
Promotion.EngagementEventState.END -> {
// 促銷視圖曝光完成（在促銷窗口關閉後發送）
}
else -> {}
}
Promotion.EngagementEventType.COUPON -> when(engagementEventState) {
Promotion.EngagementEventState.START -> {
// 開始優惠券消費請求
}
Promotion.EngagementEventState.END -> {
// 完成優惠券消費請求並發送響應
}
else -> {}
}
Promotion.EngagementEventType.EVENT -> {
// 如果主機是遊戲，發送 JSONObject 結果值
if (param == null) {
return
}
val api = param.optString("api")
val param = param.optString("param")
// TODO: 根據 api 和 param 值執行以下操作
}
Promotion.EngagementEventType.IAP_UPDATED -> when (engagementEventState) {
Promotion.EngagementEventState.START -> {
// 信號以接受購買歷史已更改（調用 Restore() 方法）
}
Promotion.EngagementEventState.END -> {
// 信號以接受購買歷史已更改（調用 Restore() 方法）
val iapUpdateType = param?.optString("type")
if (iapUpdateType == "subscription") {
// TODO: 恢复订阅产品
IAPV4.restoreSubscription(object : IAPV4.IAPV4RestoreListener {
override fun onIAPV4Restore(
result: ResultAPI,
iapv4ReceiptList: ArrayList<IAPV4.IAPV4Receipt>?
) {
if (!result.isSuccess) {
return
}
// TODO: 使用接收到的iapv4ReceiptList请求收据验证
}
})
} else {
IAPV4.restore(object : IAPV4.IAPV4RestoreListener {
override fun onIAPV4Restore(
result: ResultAPI,
iapv4ReceiptList: ArrayList<IAPV4.IAPV4Receipt>?
) {
if (!result.isSuccess) {
return
}
// TODO: 使用接收到的iapv4ReceiptList请求收据验证
}
})
}
}
else -> {}
}
Promotion.EngagementEventType.IAP_PURCHASE -> when (engagementEventState) {
Promotion.EngagementEventState.START -> {
// 透過 IAPPurchase 架構顯示購買項目的彈出窗口。
}
Promotion.EngagementEventState.END -> {
// 透過 IAPPurchase 架構傳達請求項目的購買是否成功。
if (!result.isSuccess) {
return
}
val iapV4Receipt = param?.optJSONObject("iapV4Receipt")
}
else -> {}
}
Promotion.EngagementEventType.SOCIAL_MYINQUIRY_VIEW -> when (engagementEventState) {
Promotion.EngagementEventState.START -> {
// 開始我的詢問頁面曝光請求
}
Promotion.EngagementEventState.END -> {
// 我的詢問頁面已曝光（在我的詢問窗口關閉後發送）
}
else -> {}
}
Promotion.EngagementEventType.SOCIAL_PROFILE_VIEW -> when (engagementEventState) {
Promotion.EngagementEventState.START -> {
// 發起個人資料頁面曝光請求
}
Promotion.EngagementEventState.END -> {
// 個人資料頁面曝光完成（在關閉個人資料窗口後交付）
}
else -> {}
}
else -> {}
}
}
})
API 參考: com.hive.Promotion.setEngagementListener
import com.hive.IAPV4;
import com.hive.Promotion;
import com.hive.ResultAPI;
Promotion.INSTANCE.setEngagementListener((result, engagementEventType, engagementEventState, param) -> {
switch (engagementEventType) {
case EVENT_TYPE:
switch (engagementEventState) {
case BEGIN:
// 所有的参与操作都已执行
break;
case FINISH:
// 所有的参与操作已完成
break;
}
break;
case AUTH_LOGIN_VIEW:
switch (engagementEventState) {
case START:
// 开始会员登录页面曝光请求
break;
case END:
// 会员登录完成（在登录完成/窗口关闭后发送）
break;
}
break;
case SOCIAL_INQUIRY_VIEW:
switch (engagementEventState) {
case START:
// 开始1:1咨询页面曝光请求
break;
case END:
// 1:1咨询页面曝光完成（在1:1咨询窗口关闭后发送）
break;
}
break;
case PROMOTION_VIEW:
switch (engagementEventState) {
case START:
// 开始促销视图展示请求
break;
case END:
// 促销视图曝光完成（在促销窗口关闭后发送）
break;
}
break;
case COUPON:
switch (engagementEventState) {
case START:
// 开始优惠券消费请求
break;
case END:
// 完成优惠券消费请求并发送响应
break;
}
break;
case EVENT:
// 如果主机是游戏，发送JSONObject结果值
if (param == null)
return;
String api = param.optString("api");
String paramData = param.optString("param");
// TODO: Perform the following actions according to the api and param values
break;
case IAP_UPDATED:
switch (engagementEventState) {
case START:
// Signal to accept as purchase history has changed (call Restore() method)
break;
case END:
// Signal to accept as purchase history has changed (call Restore() method)
if(param == null)
return;
String iapUpdateType = param.optString("type");
if(iapUpdateType == "subscription") {
// TODO: 恢复订阅产品
IAPV4.INSTANCE.restoreSubscription((result1, iapv4ReceiptList) -> {
if (!result1.isSuccess()) {
return;
}
// TODO: 使用接收到的iapv4ReceiptList请求收据验证
});
} else {
IAPV4.INSTANCE.restore((result2, iapv4ReceiptList) -> {
if (!result2.isSuccess()) {
return;
}
// TODO: 使用接收到的iapv4ReceiptList请求收据验证
});
}
break;
}
break;
case IAP_PURCHASE:
switch (engagementEventState) {
case START:
// 显示通过IAPPurchase架构接收的购买项目的弹出窗口。
break;
case END:
// 通过IAPPurchase架构传达请求的项目购买是否成功。
if(!result.isSuccess() || param == null)
return;
JSONObject iapV4Receipt = param.optJSONObject("iapV4Receipt");
break;
}
break;
case SOCIAL_MYINQUIRY_VIEW:
switch (engagementEventState) {
case START:
// 開始我的查詢頁面曝光請求
break;
case END:
// 我的查詢頁面已曝光（在我的查詢視窗關閉後發送）
break;
}
break;
case SOCIAL_PROFILE_VIEW:
switch (engagementEventState) {
case START:
// 發起個人資料頁面曝光請求
break;
case END:
// 個人資料頁面曝光完成（在關閉個人資料視窗後發送）
break;
}
break;
}
});
API 參考: setEngagementHandler(_:)
import HIVEService
PromotionInterface.setEngagementHandler() { result, engagementEventType, engagementState, param in
switchengageEventType {
case.type:
switch engagementState{
case .begin:
// 所有的参与动作都已执行
case .finish:
// 所有的参与动作都已完成
}
case .authLoginView:
switch engagementState {
case.eventStart:
// 開始會員登入頁面曝光請求
case .eventEnd:
// 會員登入完成（在登入完成/視窗關閉後交付）
}
case .socialInquiryView:
switch engagementState {
case.eventStart:
// 開始 1:1 諮詢頁面曝光請求
case .eventEnd:
// 1:1 諮詢頁面曝光完成（在 1:1 諮詢窗口關閉後交付）
}
案例 .promotionView:
切換 engagementState {
案例.eventStart:
// 開始促銷視圖印象請求
案例 .eventEnd:
// 促銷視圖曝光完成（在促銷窗口關閉後交付）
}
案例 .coupon:
切換 engagementState {
案例.eventStart:
// 開始優惠券消費請求
案例 .eventEnd:
// 完成優惠券消費請求並發送響應
}
case.event:
// 如果主機是遊戲，發送JSONObject結果值
let api = param?["api"]
let param = param?["param"]
// 根據 api 和參數值執行請求的操作
case.iapPromote:
switch engagementState {
case.eventStart:
// 傳達是否存在 IAP Promote 數據
case.eventEnd:
if ! result.isSuccess() {
return
}
// 由於存在 IAP Promote 數據，marketPid 是通過檢查 Promote API 獲得的。
IAPV4Interface.checkPromotePurchase() {
promoteResult,
marketPid in
if !promoteResult.isSuccess() {
return
}
// TODO: 請求購買交付的 market Pid 項目
IAPV4Interface.purchase(marketPid, additionalInfo: nil) {
purchaseResult,
receipt in
if !purchaseResult.isSuccess() {
return
}
// TODO: 請求使用收到的收據進行驗證
}
}
case.iapUpdated:
switch engagementState {
case.eventStart:
// 信号接收，因为购买详情已更改
case.eventEnd:
// 信号接收，因为购买详情已更改
if
let type = param ? ["type"],
type == "subscription" {
// TODO: 恢复订阅产品
IAPV4Interface.restoreSubscription() {
(result, receiptList) in
// TODO: 使用收到的receiptList请求收据验证
}
return
}
// TODO: 恢复可消耗商品
IAPV4Interface.restore() {
(result, receiptList) in
// TODO: 使用收到的receiptList请求收据验证
}
}
case.iapPurchase:
switch engagementState {
case.eventStart:
// 显示通过IAPPurchase架构购买项目的弹出窗口。
case.eventEnd:
// 通过IAPPurchase架构传达请求项目的购买是否成功。
if result.isSuccess() {
let receipt = param ? ["iapV4Receipt"];
}
}
case.socialMyInquiry:
switch engagementState {
case.eventStart:
// 开始我的查询页面曝光请求
case.eventEnd:
// 我的查询页面已曝光（在关闭我的查询窗口后交付）
}
case.socialProfile:
switch engagementState {
case.eventStart:
// 发起个人资料页面曝光请求
case.eventEnd:
// 个人资料页面曝光完成（在关闭个人资料窗口后交付）
}
}
}
API 參考: HIVEPromotion setEngagementHandler
#import <HIVEService/HIVEService-Swift.h>
[HIVEPromotion setEngagementHandler: ^(HIVEResultAPI *result, HIVEEngagementEventType engagementEventType, HIVEEngagementEventState engagementState, NSDictionary *param) {
switch (engagementEventType) {
case HIVEEngagementEventTypeType:
switch (engagementState) {
case HIVEEngagementStateBegin:
// 所有的参与动作都已执行
break;
case HIVEEngagementStateFinish:
// 所有的参与动作都已完成
break;
}
break;
case HIVEEngagementEventTypeAuthLoginView:
switch (engagementState) {
case HIVEEngagementStateEventStart:
// 開始會員登入頁面曝光請求
break;
case HIVEEngagementStateEnd:
// 會員登入完成（在登入完成/視窗關閉後交付）
break;
}
break;
案例 HIVEEngagementEventTypeSocialInquiryView:
切換 (engagementState) {
案例 HIVEEngagementStateEventStart:
// 開始 1:1 諮詢頁面曝光請求
休息;
案例 HIVEEngagementStateEnd:
// 1:1 諮詢頁面曝光完成 (在 1:1 諮詢窗口關閉後交付)
休息;
}
休息;
case HIVEEngagementEventTypePromotionView:
switch (engagementState) {
case HIVEEngagementStateEventStart:
// 開始促銷視圖印象請求
break;
case HIVEEngagementStateEnd:
// 促銷視圖曝光完成（在促銷窗口關閉後交付）
break;
}
break;
case HIVEEngagementEventTypeCoupon:
switch (engagementState) {
case HIVEEngagementStateEventStart:
// 開始優惠券消費請求
break;
case HIVEEngagementStateEnd:
// 完成優惠券消費請求並發送回應
break;
}
break;
案例 HIVEEngagementEventTypeEvent:
// 如果主机是游戏，发送 JSONObject 结果值
如果 (param == nil) {
返回;
}
NSString * api = [param objectForKey: @ "api"];
NSSString * param = [param objectForKey: @ "param"];
// TODO: 根据 api 和 param 值执行请求的操作
break;
案例 HIVEEngagementEventTypeIapPromote:
开关 (engagementState) {
案例 HIVEEngagementStateEventStart:
// 传达是否存在 IAP Promote 数据
休息;
案例 HIVEEngagementStateEventEnd:
如果 (![result isSuccess]) {
返回;
}
// 由于存在 IAP Promote 数据，marketPid 通过检查 Promote API 接收。
[HIVEIAPV4 checkPromotePurchase: ^ (HIVEResultAPI * promoteResult, NSString * marketPid) {
如果 (![promoteResult isSuccess]) {
返回;
}
// TODO: 使用接收到的 market Pid 请求购买项目
[HIVEIAPV4 purchase: marketPid additionalInfo: nil handler: ^ (HIVEResultAPI * purchaseResult, HIVEIAPV4Receipt * receipt) {
如果 (![purchaseResult isSuccess]) {
返回;
}
// TODO: 使用接收到的收据请求验证收据
}];
}];
休息;
}
休息;
案例 HIVEEngagementEventTypeIapUpdated:
开关 (engagementState) {
案例 HIVEEngagementStateEventStart:
// 由于购买详情已更改，发出接收信号
休息;
案例 HIVEEngagementStateEventEnd:
// 由于购买详情已更改，发出接收信号
NSString * type = [param objectForKey: @ "type"];
如果 (type != nil && [type isEqualToString: @ "subscription"]) {
// TODO: 恢复订阅产品
[HIVEIAPV4 restoreSubscription: ^ (HIVEResultAPI * result, NSArray < HIVEIAPV4Receipt * > * receiptList) {
// TODO: 使用接收到的 receiptList 请求收据验证
}];
返回;
}
// TODO: 恢复消耗品
[HIVEIAPV4 restore: ^ (HIVEResultAPI * result, NSArray < HIVEIAPV4Receipt * > * receiptList) {
// TODO: 使用接收到的 receiptList 请求收据验证
}];
休息;
}
案例 HIVEEngagementEventTypeIapPurchase:
开关 (engagementState) {
案例 HIVEEngagementStateEventStart:
// 显示通过 IAPPurchase 模式接收的购买项目的弹出窗口。
休息;
案例 HIVEEngagementStateEventEnd:
// 通过 IAPPurchase 模式传达请求项目的购买是否成功。
如果(![result isSuccess]) {
返回;
}
HIVEIAPV4Receipt * receipt = [param objectForKey: @ "iapV4Receipt"];
休息;
}
休息;
案例 HIVEEngagementEventTypeSocialMyInquiry:
开关 (engagementState) {
案例 HIVEEngagementStateEventStart:
// 开始我的询问页面曝光请求
休息;
案例 HIVEEngagementStateEnd:
// 我的询问页面已曝光（在我的询问窗口关闭后交付）
休息;
}
休息;
案例 HIVEEngagementEventTypeSocialProfile:
开关 (engagementState) {
案例 HIVEEngagementStateEventStart:
// 启动个人资料页面曝光请求
休息;
}
案例 HIVEEngagementStateEnd:
// 個人資料頁面曝光完成（在關閉個人資料窗口後交付）
休息;
}
休息;
}
}];
設定以處理用戶參與事件¶
Hive SDK 通常能够处理传入请求，如果登录完成。然而，在第一次执行等情况下，即使登录后，如果在游戏服务器数据库创建之前，补偿支付等可能无法进行。因此，您需要告知 Hive SDK 游戏是否可以处理 UE 事件。
- 事件處理的預設設定為
false。 - 如果事件處理設為
true，則現有的排隊事件會立即處理，隨後的事件也會立即處理。 - 如果事件處理設為
false，則進來的事件會排隊，直到設定轉換為true。 - 設定為
true應在 登錄 之後呼叫，而設定為false則對呼叫的時間沒有限制。 - （使用 Hive SDK v4.4.0 及以後版本）所有使用 Hive SDK 的遊戲都必須實現此 API 以提供 CPI 獎勵。
- 如果用戶通過用戶獲取生成的邀請鏈接或 QR 碼，或通過獎勵牆頁面進入應用，則根據通過調用此 API 變更的狀態執行進入歷史轉移和獎勵支付請求。
- 您必須在遊戲可以執行 UE 功能的時候呼叫此 API。
Note
- 在**Promotion**類別中使用
setAdditionalInfo()方法，在調用setEngagementReady()方法之前發送當前用戶的遊戲數據。使用優惠券或用戶獲取發送的遊戲信息對遊戲工作室可用。 - 根據Hive SDK的版本，
setEngagementReady()方法的類別有所不同。
Hive SDK v4.5.0 及更高版本¶
在**Promotion**类中使用setEngagementReady()方法来设置UE事件是否可用以处理。以下是将其设置为true的示例代码。
API 參考: Promotion::setEngagementReady
API 參考: Promotion.setEngagementReady
API 參考: HIVEPromotion:setEngagementReady
兌換優惠券請求的結果代碼¶
如果在处理优惠券事件时出现促销代码错误或其他问题，UE模块会根据Hive定义的错误代码显示弹出窗口，以通知用户情况。 
優惠券方案 URL 的主機值始終為 hive。
| 代碼 | 描述 | 代碼 | 描述 |
|---|---|---|---|
| 200 | 訪問錯誤的參數 | 305 | 獨特優惠券過期可用數量 |
| 201 | 發送錯誤的哈希值 | 306 | 優惠券已過期 |
| 202 | 超過帳戶的使用限制 | 307 | 缺少區分新/現有用戶或活躍用戶系統錯誤所需的數據 |
| 203 | 優惠券的可用數量超過 | 308 | 不是此事件的目標。僅限現有用戶 |
| 204 | AppID與發放的優惠券不匹配 | 309 | 不是此事件的目標。僅限新用戶 |
| 300 | 錯誤數字代碼的優惠券 | 310 | 新/現有事件未在遊戲中註冊 |
| 301 | 在收到的促銷中沒有優惠券數據 | 400 | 發送所有項目失敗 |
| 302 | 搜索優惠券代碼失敗 | 401 | 發送多個項目失敗 |
| 303 | 優惠券正在使用中 | 500 | 數據庫錯誤 |
| 304 | 已使用的優惠券 | 501 | 通信故障 |