跳轉至

用户参与 (UE, 深度链接)

用戶參與(UE)提供深度鏈接功能,配合優惠券,允許通過輕觸鏈接邀請遊戲用戶到遊戲中的特定位置或事件頁面,或直接獲得獎勵。

在 Hive SDK 中,您希望通过方案 URL 执行的操作称为用户参与操作。当游戏执行给定 URL 中指定的操作时,Hive 以用户参与事件的形式向游戏发出请求。

什麼是用戶參與?

UE 是一項服務,能夠從應用程序內部和外部執行請求,並執行以下功能:

  • 透過深層連結或推播通知從應用程式外部執行方案 URL。
  • 透過互動從應用程式內部執行方案 URL。
  • 使用 Hive SDK v4.4.0 及更高版本,
    • 通過用戶獲取創建的 QR 碼和連結等外部路徑將訪問歷史發送到遊戲應用程式以請求獎勵。
    • 通過 offerwall 或 Hive SDK 的其他功能將訪問歷史發送到遊戲應用程式以請求獎勵。(請求 CPI 獎勵)
    • 確保遊戲客戶端實現 setEngagementReady API,並在 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 傳遞給應用程式:

推送

無論目標應用程式是否正在運行,接收該 Scheme URL 的接收者都會收到包含 Scheme URL 的推送消息。當接收者點擊該消息時,推送 Scheme URL 將發送到 Hive 客戶端,然後 Hive 客戶端處理該 URL。

  • 例如,push://{host}/{path}?{query}
深層連結

如果用戶通過外部方式(例如短信和網頁瀏覽器)點擊一個 URL,並且該 URL 的 scheme 欄位填寫了用戶設備上特定遊戲的 AppID,則該遊戲將被執行,並且該 URL 將被傳遞到 Hive SDK。如果遊戲應用未安裝,則將轉到安裝頁面。

  • 例如,com.com2us.example://{host}/{path}?{query}

使用深度链接方案时,用户所遵循的内容会根据游戏安装的状态而有所不同。

1. <b>如果遊戲已安裝</b>
當用戶點擊深層鏈接時,用戶首先檢查遊戲提示,然後進入遊戲。
![](https://developers.withhive.com/wp-content/uploads/2024/05/deep_link_installed_240517.png){width="700px"}
2. <b>如果遊戲未安裝</b>
當用戶點擊消息中的鏈接時,會通知用戶在遊戲安裝後可以獲得獎勵。由於遊戲未安裝,將轉移到下載市場(Google Play商店 / Apple App Store)。
![](http://developers.withhive.com/wp-content/uploads/2018/04/23_develop-promotion_userengagement_3_en.png){width="700px"}
Interwork

如果用户在应用程序运行时触摸Hive SDK的促销屏幕(横幅、通知等)的特定链接URL,并且该URL的方案字段为“interwork”,则该URL将传递给Hive SDK。

  • 例如,interwork://{host}/{path}?{query}

您可以使用 processURI API 直接从游戏发送 URL 到 Hive SDK 来调用处理互操作方案的请求。

String uri = "";


Boolean result = Promotion.processURI(uri);

if(result) {
        // 成功註冊 UE 事件
} else {
        // 不適合的格式的方案 URI
}
std::string uri = "";


bool result = Promotion::processURI(uri);

if(result) {
        // 成功註冊 UE 事件
} else {
        // 不適合的格式的方案 URI
}
String uri = "";


boolean result = Promotion.processURI(uri);

if(result) {
        // 成功註冊 UE 事件
} else {
        // 不適合的格式用於方案 URI
}
NSString* uri = @"";


bool result = [HIVEPromotion processURI:uri];

if(result) {
        // 成功註冊 UE 事件
} else {
        // 不適合的格式於方案 URI
}

主機

主機 指定誰負責所請求的行動:

  • 遊戲: 遊戲負責的行動
  • 蜂巢: Hive SDK 負責的行動

常見欄位

Scheme URL 的通用字段是 /{api}/{parameters},它指示要处理的操作,包括所需的信息:

API 澄清了通过 URL 采取什么行动。根据主机可以采取以下行动:

如果方案 URL 的主機是

請注意,根據身份驗證版本(v4或v1),可用的API是不同的。

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
offerwallshow promotion/offerwall 提供牆曝光 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 接收通知。遊戲可能需要進行一些工作,例如根據需要暫停遊戲。

有關 iappromoteiappurchase 的更多資訊,請參見以下內容。

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。
同步 iappurchase 與 Spot Banner

如果您想通過使用 iappurchase 計劃來銷售商品,請利用 Spot Banner。查看使用 Spot Banner 的指導

  • 在遊戲中設置一個特定位置或時機的廣告橫幅 ID,以鼓勵用戶購買物品。
  • 調用廣告橫幅 ID。當用戶點擊廣告橫幅時,實施互動方案。註冊的 EngagementListener 將發送互動的運行狀態。
  • 如果調用互動方案,則實施購買邏輯。因此,請確保在執行方案之前初始化市場並獲取商店信息。這意味著,在調用廣告橫幅之前,實施 marketConnect APIgetProductInfo 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 格式發送結果。結果分為 schemeapiparam 鍵。確保遊戲在接收到值後適時執行相關操作。

  • 例如,將物品放入郵箱
    • URL 方案 : com.com2us.example://game/postboxadditem?item_id=123456&item_title=item01
    • 來自 Hive SDK 的 JSONObject 結果

      {
      "scheme" : "com.com2us.example",
      "api" : "/postboxadditem",
      "param" : "item_id=123456&item"
      }
      

有關如何實現用戶參與的更多詳細信息,請參閱 實現用戶參與 > 聲明和註冊全局回調示例代碼

專案設定

在遊戲應用程式中使用 UE,請在構建應用程式之前由操作系統設置。

Android 設定

launchMode 方法設置為 singleTasksingleTop。該方法是 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 設定

  1. 在 Xcode TARGETS 列表中選擇您想要開發的應用程序的版本。
  2. 選擇 Info 標籤。
  3. URL Types 部分添加 Additional url type properties 項目,以在 Bundle IdentifierURL 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.OFFERWALL_VIEW:    
                 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: restore subscription product    
                            IAPV4.restoreSubscription((ResultAPI result, List <hive.IAPV4.IAPV4Receipt> receiptList) => {    
                                if (!result.isSuccess()) {    
                                    return;    
                                }    
                                // TODO: Request receipt verification using the received 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::OFFERWALL_VIEW:
                        switch (EngagementEventState) {
                                case EHiveEngagementEventState::EVENT_START:
                                        // 開始請求顯示優惠牆頁面
                                        break;
                                case EHiveEngagementEventState::EVENT_END:
                                        // 完成顯示優惠牆頁面(在優惠牆窗口關閉後交付)
                                        break;
                        }
                        break;

                case EHiveEngagementEventType::EVENT:
                        // 如果主機是遊戲,傳遞 Param 結果值 (鍵: "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:
                                        // The purchase history has changed, so signal to receive it
                                        FString TypeValue;
                                        if (Param.IsValid() && Param->TryGetStringField(TEXT("type"), TypeValue)) {
                                                if (TypeValue == TEXT("subscription")) {
                                                        // TODO: Restore subscription products
                                                } else {
                                                        // TODO: Restore consumable products
                                                }
                                        }

                                        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::OFFERWALL_VIEW:    
                    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: 恢复订阅产品    
                            IAPV4::restoreSubscription([ = ](ResultApi    
                                const & result, vector < reference_wrapper < IAPV4Receipt >> receiptList) {    
                                if (!result.isSuccess()) {    
                                    return;    
                                }    
                                // TODO: 使用接收到的 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 -> {    
                                        // 所有的 Engagement 行為都已執行    
                                    }    
                                    Promotion.EngagementEventState.FINISH -> {    
                                        // 所有的 Engagement 行為都已完成    
                                    }    
                                    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.OFFERWALL_VIEW -> 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 OFFERWALL_VIEW:    
                    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:    
                         // 所有的参与动作都已完成    
                 }    

             案例 .authLoginView:    
                 切換 engagementState {    
                     案例.eventStart:    
                         // 開始會員登錄頁面曝光請求    
                     案例 .eventEnd:    
                         // 會員登錄完成(在登錄完成/窗口關閉後交付)    
                 }    

             案例 .socialInquiryView:    
                 切換 engagementState {    
                     案例.eventStart:    
                         // 開始 1:1 諮詢頁面曝光請求    
                     案例 .eventEnd:    
                         // 1:1 諮詢頁面曝光完成(在 1:1 諮詢窗口關閉後交付)    
                 }    

             案例 .promotionView:    
                 切換 engagementState {    
                     案例.eventStart:    
                         // 開始促銷視圖印象請求    
                     案例 .eventEnd:    
                         // 促銷視圖曝光完成(在促銷窗口關閉後交付)    
                 }    

             case .coupon:    
                 switch engagementState {    
                     case.eventStart:    
                         // 開始優惠券消費請求    
                     case .eventEnd:    
                         // 完成優惠券消費請求並發送回應    
                 }    

             案例 .offerwallView:    
                 切換 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;    

                案例 HIVEEngagementEventTypeAuthLoginView:    
                    切換 (engagementState) {    
                        案例 HIVEEngagementStateEventStart:    
                            // 開始會員登錄頁面曝光請求    
                            休息;    
                        案例 HIVEEngagementStateEnd:    
                            // 會員登錄完成(在登錄完成/窗口關閉後交付)    
                            休息;    
                    }    
                    休息;    

                案例 HIVEEngagementEventTypeSocialInquiryView:    
                    切換 (engagementState) {    
                        案例 HIVEEngagementStateEventStart:    
                            // 開始 1:1 諮詢頁面曝光請求    
                            休息;    
                        案例 HIVEEngagementStateEnd:    
                            // 1:1 諮詢頁面曝光完成 (在 1:1 諮詢窗口關閉後交付)    
                            休息;    
                    }    
                    休息;    

                case HIVEEngagementEventTypePromotionView:    
                    switch (engagementState) {    
                        case HIVEEngagementStateEventStart:    
                            // 開始促銷視圖印象請求    
                            break;    
                        case HIVEEngagementStateEnd:    
                            // 促銷視圖曝光完成(在促銷窗口關閉後交付)    
                            break;    
                    }    
                    break;    

                案例 HIVEEngagementEventTypeCoupon:    
                    切換 (engagementState) {    
                        案例 HIVEEngagementStateEventStart:    
                            // 開始優惠券消費請求    
                            休息;    
                        案例 HIVEEngagementStateEnd:    
                            // 完成優惠券消費請求並發送響應    
                            休息;    
                    }    
                    休息;    

                案例 HIVEEngagementEventTypeOfferwallView:    
                    切換 (engagementState) {    
                        案例 HIVEEngagementStateEventStart:    
                            // 開始提供牆頁面曝光請求    
                            休息;    
                        案例 HIVEEngagementStateEnd:    
                            // 完成提供牆頁面曝光(在關閉提供牆窗口後交付)    
                            休息;    
                    }    
                    休息;    

                case HIVEEngagementEventTypeEvent:    
                    // 如果主机是游戏,发送JSONObject结果值    
                    if (param == nil) {    
                        return;    
                    }    
                    NSString * api = [param objectForKey: @ "api"];    
                    NSSString * param = [param objectForKey: @ "param"];    
                    // TODO: 根据api和param值执行请求的操作    
                    break;    

                case HIVEEngagementEventTypeIapPromote:    
                    switch (engagementState) {    
                        case HIVEEngagementStateEventStart:    
                            // 传达是否存在 IAP 推广数据    
                            break;    
                        case HIVEEngagementStateEventEnd:    
                            if (![result isSuccess]) {    
                                return;    
                            }    
                            // 由于存在 IAP 推广数据,marketPid 通过检查推广 API 接收。    
                            [HIVEIAPV4 checkPromotePurchase: ^ (HIVEResultAPI * promoteResult, NSString * marketPid) {    
                                if (![promoteResult isSuccess]) {    
                                    return;    
                                }    
                                // TODO: 使用接收到的 market Pid 请求购买项目    
                                [HIVEIAPV4 purchase: marketPid additionalInfo: nil handler: ^ (HIVEResultAPI * purchaseResult, HIVEIAPV4Receipt * receipt) {    
                                    if (![purchaseResult isSuccess]) {    
                                        return;    
                                    }    
                                    // TODO: 请求使用接收到的收据验证收据    
                                }];    
                            }];    
                            break;    
                        }    
                    break;    
                case HIVEEngagementEventTypeIapUpdated:    
                    switch (engagementState) {    
                    case HIVEEngagementStateEventStart:    
                        // 信号接收,因为购买详情已更改    
                        break;    
                    case HIVEEngagementStateEventEnd:    
                        // 信号接收,因为购买详情已更改    
                        NSString * type = [param objectForKey: @ "type"];    
                        if (type != nil && [type isEqualToString: @ "subscription"]) {    
                            // TODO: 恢复订阅产品    
                            [HIVEIAPV4 restoreSubscription: ^ (HIVEResultAPI * result, NSArray < HIVEIAPV4Receipt * > * receiptList) {    
                                // TODO: 使用接收到的 receiptList 请求收据验证    
                            }];    
                            return;    
                        }    
                        // TODO: 恢复消耗品    
                        [HIVEIAPV4 restore: ^ (HIVEResultAPI * result, NSArray < HIVEIAPV4Receipt * > * receiptList) {    
                            // TODO: 使用接收到的 receiptList 请求收据验证    
                        }];    
                        break;    
                    }    
                case HIVEEngagementEventTypeIapPurchase:    
                    switch (engagementState) {    
                    case HIVEEngagementStateEventStart:    
                        // 通过 IAPPurchase 模式显示购买项目的弹出窗口。    
                        break;    
                    case HIVEEngagementStateEventEnd:    
                        // 通过 IAPPurchase 模式传达请求项目的购买是否成功。    
                        if(![result isSuccess]) {    
                            return;    
                        }    
                        HIVEIAPV4Receipt * receipt = [param objectForKey: @ "iapV4Receipt"];    
                        break;    
                    }    
                break;    
                case HIVEEngagementEventTypeSocialMyInquiry:    
                    switch (engagementState) {    
                    case HIVEEngagementStateEventStart:    
                        // 开始我的询问页面曝光请求    
                        break;    
                    case HIVEEngagementStateEnd:    
                        // 我的询问页面已曝光(在我的询问窗口关闭后交付)    
                        break;    
                    }    
                break;    
                case HIVEEngagementEventTypeSocialProfile:    
                    switch (engagementState) {    
                    case HIVEEngagementStateEventStart:    
                        // 发起个人资料页面曝光请求    
                        break;    
                    案例 HIVEEngagementStateEnd:    
                        // 個人資料頁面曝光完成(在關閉個人資料窗口後交付)    
                        break;    
                    }    
                break;    
                }    
}];

設定以處理用戶參與事件

Hive SDK 通常能夠處理進來的請求,如果登錄已完成。然而,在第一次執行等情況下,即使登錄後,如果在遊戲伺服器 DB 創建之前,補償支付等可能無法進行。因此,您需要告知 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 參考: hive.Promotion.setEngagementReady

using hive;    
    Boolean isReady = true;    
    ResultAPI result = Promotion.setEngagementReady(isReady);    
    if (result.isSuccess()) {    
        // call successful    
}
#include "HivePromotion.h"

bool bIsReady = true;
TOptional<FHiveResultAPI> Result = FHivePromotion::SetEngagementReady(bIsReady);

if (Result.IsSet()) {
        FHiveResultAPI& ResultAPI = Result.GetValue();
        if (ResultAPI.IsSuccess()) {
                // API 呼叫成功
        }
}

API 參考: Promotion::setEngagementReady

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    bool isReady = true;    
    ResultAPI result = Promotion::setEngagementReady(isReady);    
    if (result.isSuccess()) {    
        // call successful    
}

API 參考: Promotion.setEngagementReady

import com.hive.Promotion    
    import com.hive.ResultAPI    
    val isReady = true    
    val result = Promotion.setEngagementReady(isReady)    
    if (result.isSuccess) {    
         // call successful    
}

API 參考: com.hive.Promotion.setEngagementReady

import com.hive.Promotion;    
    import com.hive.ResultAPI;    
    boolean isReady = true;    
    ResultAPI result = Promotion.INSTANCE.setEngagementReady(isReady);    
    if (result.isSuccess()) {    
         // call successful    
}

API 參考: PromotionInterface .setEngagementReady

import HIVEService    
    let isReady = true    
    let result = PromotionInterface.setEngagementReady(isReady)    
    if (result.isSuccess()) {    
    // call successful    
}

API 參考: HIVEPromotion:setEngagementReady

#import <HIVEService/HIVEService-Swift.h>    
    BOOL isReady = YES;    
    HIVEResultAPI *result = [HIVEPromotion setEngagementReady: isReady];    
    if ([result isSuccess]) {    
        // call successful    
}

兌換優惠券請求的結果代碼

如果在處理優惠券事件時出現促銷代碼錯誤或其他問題,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 通信失敗