跳转至

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

用户参与(UE)提供了带优惠券的深度链接功能,允许通过简单点击链接邀请游戏用户到游戏中的特定位置或活动页面,或直接获得奖励。

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

什么是用户参与?

UE是一个从应用程序内部和外部执行请求的服务,并执行以下功能:

  • 通过深度链接或推送通知从应用外部执行方案 URL。
  • 通过互操作从应用内部执行方案 URL。
  • 使用 Hive SDK v4.4.0 及更高版本,
    • 通过用户获取创建的二维码和链接等外部途径将访问历史发送到游戏应用以请求奖励。
    • 通过 Hive SDK 的广告墙或其他功能将访问历史发送到游戏应用以请求奖励。(请求 CPI 奖励)
    • 确保游戏客户端实现 setEngagementReady API,并在 Hive SDK 模块可用时发送请求以执行 UE 功能以处理 CPI 奖励等。

如何指示方案 URL

方案 URL 是一种表达 UE 行动的格式。它指示在方案 URL 中定义了什么行动以及适用于谁。使用 Hive 的方案 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 的游戏应用是否正在运行,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. 如果游戏已安装 当用户点击深度链接时,用户首先检查游戏提示,然后进入游戏。
  2. 如果游戏未安装 当用户在消息中点击链接时,会通知用户在游戏安装后可获得奖励。由于游戏未安装,用户将被转移到下载市场(Google Play 商店 / Apple App Store)。
互操作

如果用户在应用程序运行时触摸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 {
        // 不适合Scheme URI的格式
}
String uri = "";


boolean result = Promotion.processURI(uri);

if(result) {
        // 成功注册UE事件
} else {
        // 不适合Scheme URI的格式
}
NSString* uri = @"";


bool result = [HIVEPromotion processURI:uri];

if(result) {
        // 成功注册UE事件
} else {
        // 不适合的Scheme URI格式
}

主机

主机指定谁对请求的操作负责:

  • 游戏: 游戏负责的动作
  • 蜂巢: 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
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。
与Spot Banner同步iappurchase

如果您想通过使用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 正在处理 Scheme 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,需在构建应用之前由操作系统设置。

安卓设置

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. 选择 信息 选项卡。
  3. URL 类型 部分添加 附加 URL 类型属性 项,以在 Bundle IdentifierURL Schemes 字段中输入 AppID。

实现用户参与

声明和注册全局回调

声明并注册全局回调以应用 UE。声明和注册的方式取决于 Hive SDK 的版本。

Note
  • 从 Hive SDK v4.5.0 及更高版本开始,全局回调声明和注册通过 Promotion 类的处理程序注册 API 完成。
  • Engagement Handler 格式和枚举值从 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:    
                         // 所有的 Engagement 操作都已执行    
                         break;    
                     case EngagementEventState.FINISH:    
                         // 所有的 Engagement 操作已完成    
                         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: 恢复订阅产品    
                            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:
                                        // 蜂巢会员登录页面显示请求开始
                                        break;
                                case EHiveEngagementEventState::EVENT_END:
                                        // 蜂巢会员登录执行完成(在登录完成/窗口关闭执行后通过)
                                        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:
                                        // Promotion View曝光请求开始
                                        break;
                                case EHiveEngagementEventState::EVENT_END:
                                        // Promotion View曝光完成(在关闭Promotion窗口后交付)
                                        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:
                        // 如果主机是游戏,传递参数结果值(键:"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 Promote 数据,我们通过检查 Promote 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:    
                        // Engagement的所有操作都已执行    
                        break;    
                    case EngagementEventState::FINISH:    
                        // Engagement的所有操作都已完成    
                        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 View 展示请求    
                                    }    
                                    Promotion.EngagementEventState.END -> {    
                                        // Promotion View 曝光完成(在 Promotion 窗口关闭后发送)    
                                    }    
                                    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:    
                         // 所有的参与行为都已完成    
                 }    

             case .authLoginView:    
                 switch engagementState {    
                     case.eventStart:    
                         // 开始会员登录页面曝光请求    
                     case .eventEnd:    
                         // 会员登录完成(在登录完成/窗口关闭后发送)    
                 }    

             case .socialInquiryView:    
                 switch engagementState {    
                     case.eventStart:    
                         // 开始 1:1 咨询页面曝光请求    
                     case .eventEnd:    
                         // 1:1 咨询页面曝光完成(在 1:1 咨询窗口关闭后交付)    
                 }    

             case .promotionView:    
                 switch engagementState {    
                     case.eventStart:    
                         // 开始促销视图印象请求    
                     case .eventEnd:    
                         // 促销视图曝光完成(在促销窗口关闭后交付)    
                 }    

             case .coupon:    
                 switch engagementState {    
                     case.eventStart:    
                         // 开始优惠券消费请求    
                     case .eventEnd:    
                         // 完成优惠券消费请求并发送响应    
                 }    

             case .offerwallView:    
                 switch engagementState {    
                     case.eventStart:    
                         // 开始展示奖励墙页面请求    
                     case .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;    

                case HIVEEngagementEventTypeSocialInquiryView:    
                    switch (engagementState) {    
                        case HIVEEngagementStateEventStart:    
                            // 开始 1:1 咨询页面曝光请求    
                            break;    
                        case HIVEEngagementStateEnd:    
                            // 1:1 咨询页面曝光完成(在 1:1 咨询窗口关闭后交付)    
                            break;    
                    }    
                    break;    

                case HIVEEngagementEventTypePromotionView:    
                    switch (engagementState) {    
                        case HIVEEngagementStateEventStart:    
                            // 开始促销视图印象请求    
                            break;    
                        case HIVEEngagementStateEnd:    
                            // 促销视图曝光完成(在促销窗口关闭后交付)    
                            break;    
                    }    
                    break;    

                case HIVEEngagementEventTypeCoupon:    
                    switch (engagementState) {    
                        case HIVEEngagementStateEventStart:    
                            // 开始优惠券消费请求    
                            break;    
                        case HIVEEngagementStateEnd:    
                            // 完成优惠券消费请求并发送响应    
                            break;    
                    }    
                    break;    

                case HIVEEngagementEventTypeOfferwallView:    
                    switch (engagementState) {    
                        case HIVEEngagementStateEventStart:    
                            // 开始展示优惠墙页面请求    
                            break;    
                        case HIVEEngagementStateEnd:    
                            // 完成优惠墙页面展示(在关闭优惠墙窗口后交付)    
                            break;    
                    }    
                    break;    

                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 Promote 数据    
                            break;    
                        case HIVEEngagementStateEventEnd:    
                            if (![result isSuccess]) {    
                                return;    
                            }    
                            // 由于存在 IAP Promote 数据,marketPid 通过检查 Promote 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 通常能够处理已完成登录的传入请求。然而,在首次执行等情况下,即使登录后,如果在游戏服务器数据库创建之前,补偿支付等可能无法进行。因此,您需要告知 Hive SDK 是否可以处理 UE 事件

  • 事件处理的默认设置为 false
  • 如果事件处理设置为 true,现有的排队事件将立即处理,后续事件也将立即处理。
  • 如果事件处理设置为 false,传入事件将被排队,直到设置转换为 true
  • 将其设置为 true 应在 登录 之后调用,而将其设置为 false 对调用的时间没有限制。
  • (使用 Hive SDK v4.4.0 及更高版本)所有使用 Hive SDK 的游戏都必须实现此 API 以提供 CPI 奖励。
  • 如果用户通过用户获取生成的邀请链接或二维码,或通过 offerwall 页面进入应用,则根据调用此 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 通信失败