什么是用户获取？¶

您可以通过让用户在他们的社交网络上分享他们的邀请链接或二维码，来吸引新用户，这些功能由Hive SDK提供。当被邀请的用户安装游戏并满足特定条件（条件和奖励可以在Hive 控制台设置），例如达到特定等级时，邀请朋友的人和被邀请的人都会获得奖励。

邀请的对象不限于 Hive 用户。每个用户都会发放一个独特的邀请 URL 和一个二维码，以识别邀请他人的用户。

如果iOS用户通过邀请链接参与，将会显示以下通知页面以防止匹配丢失。

UA 应该为用户提供易于实现的目标，并给予适当的补偿，以增强他们的兴趣和参与感。

UA 特性¶

发布并分享游戏的邀请 URL/二维码
每次安装成本 (CPI)，如果朋友安装了游戏，则奖励用户和被邀请的朋友
每次行动成本 (CPA)，如果朋友在玩游戏时完成了任务，则奖励用户和被邀请的朋友

UA 邀请流程¶

要奖励，您需要实现项目。

注册用户获取活动¶

您可以在 Hive 控制台上注册 UA 活动。提供两种类型的活动。

按数量的成就活动 - 如果被邀请的朋友达成活动目标，用户和新朋友都将获得奖励
按任务的成就活动 - 如果完成任务的朋友数量达到设定的数字，用户和新朋友都将获得奖励

有关如何配置活动的更多信息，请参阅 Hive 控制台促销。

实施用户获取¶

在游戏中实现UA的邀请和活动UI，并鼓励用户安装应用。

接收活动信息和邀请 URL/二维码¶

要接收邀请 URL/二维码和活动信息，请在Promotion类中调用getAppInvitationData()方法。您可以根据来自 Hive SDK 的信息创建邀请页面或活动屏幕。

以下是请求 Hive SDK 的 URL/二维码和活动信息的示例代码。

Unity虚幻引擎C++KotlinJavaSwiftObjective-C

API 参考: hive.Promotion.getAppInvitationData

using hive;    
    Promotion.getAppInvitationData((ResultAPI result, AppInvitationData appInvitationData) => {    
        if (result.isSuccess()) {    
            // call successful    
        }    
});

#include "HivePromotion.h"

FHivePromotion::GetAppInvitationData(FHivePromotionOnAppInvitationDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveAppInvitationData& AppInvitationData) {
        if (Result.IsSuccess()) {
                // API  call success
        }
}));

API 参考: Promotion::getAppInvitationData

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    Promotion::getAppInvitationData([=](ResultAPI result, AppInvitationData appInvitationData) {    
        if (result.isSuccess()) {    
        // call successful    
        }    
});

API 参考: Promotion.getAppInvitationData

import com.hive.Promotion    
    import com.hive.ResultAPI    
    Promotion.getAppInvitationData(object : Promotion.AppInvitationDataListener {    
         override fun onAppInvitationData(result: ResultAPI, appInvitationData: Promotion.AppInvitationData?) {    
             if (result.isSuccess) {    
                 // call successful    
             }    
         }    
})

API 参考: com.hive.Promotion.getAppInvitationData

import com.hive.Promotion;    
    import com.hive.ResultAPI;    
    Promotion.INSTANCE.getAppInvitationData((result, appInvitationData) -> {    
         if (result.isSuccess()) {    
             // call successful    
         }    
});

API 参考: PromotionInterface .getAppInvitationData

import HIVEService    
    PromotionInterface.getAppInvitationData() { result, appInvitationData in    
        if result.isSuccess() {    
        // call successful    
        }    
}

API 参考: HIVEPromotion:getAppInvitationData

#import <HIVEService/HIVEService-Swift.h>    
    [HIVEPromotion getAppInvitationData: ^(HIVEResultAPI *result, HIVEAppInvitationData *appInvitationData) {    
        if ([result isSuccess]) {    
        // call successful    
        }    
}];

在调用getAppInvitationData()方法后，数据通过AppInivitationData对象发送。

AppInvitationData 对象的组成¶

字段名称	描述	类型
qrcode	游戏邀请的二维码图像（将位图图像保存为HEXA字符串类型）	字符串
inviteMessage	游戏的邀请信息	字符串
inviteCommonLink	游戏的邀请链接	字符串
inviteHivemsgLink	通过Hive消息的游戏邀请链接	字符串
eachCampaignList	每当完成活动时奖励的活动列表	AppInvitationCampaign列表
stageCampaignList	当用户达到邀请目标时奖励的活动列表	AppInvitationCampaignStage列表

Hive SDK 提供了通过社交媒体分享的功能，无法与接收活动信息和邀请 URL/二维码一起使用。使用 Hive SDK v4.11.7 中 Promotion 类提供的 showUAShare() 方法，支持以下 SNS。

Kakao Talk
LINE
Facebook
Facebook Messenger
WhatsApp
微信

使用 Hive SDK v4.11.2 及更高版本但低于 v4.11.7，可以通过在 PlatformHelper 类中使用 shareText() 和 shareMedia() 方法来实现该功能。

Warning

除上述提到的社交媒体外，还可以实现推广 API，但 Hive SDK 无法保证其实现。请确保在使用其他类型的社交媒体之前进行测试。
Facebook 不支持分享短文本，仅支持网页 URL 类型。
用户在使用 Facebook 或 LINE 时无法立即分享媒体。需要额外的操作，点击注册/发送按钮。

安卓
iOS

共享媒体文件仅在文件保存在用户设备上时可用。要共享URL，请使用文本共享功能或从URL下载文件。以下是通过社交媒体实现文件共享的示例代码。

Unity虚幻引擎C++KotlinJavaSwiftObjective-C

API 参考: hive .Promotion.showUAShare

using hive;    
    // 邀请消息    
    String inviteMessage = appInvitationData.inviteMessage;    
    // 邀请链接    
    String inviteCommonLink = appInvitationData.inviteCommonLink;    
    Promotion.showUAShare(inviteMessage, inviteCommonLink, (ResultAPI result) => {    
         if (result.isSuccess()) {    
            // 调用成功    
        }    
});

#include "HivePromotion.h"

FString 邀请消息 = TEXT("InviteMessage"); // AppInvitationData.InviteMessage;
FString 邀请链接 = TEXT("InviteLink"); // AppInvitationData.InviteCommonLink;

FHivePromotion::ShowUAShare(InviteMessage, InviteLink, FHivePromotionOnUAShareDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
        if (Result.IsSuccess()) {
                // API调用成功
        }
}));

API 参考: Promotion ::showUAShare

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    // 邀请信息    
    string inviteMessage = appInvitationData.inviteMessage.c_str();    
    // 邀请链接    
    string inviteCommonLink = appInvitationData.inviteCommonLink.c_str();    
    Promotion::showUAShare(inviteMessage, inviteCommonLink, [=](ResultAPI const &result) {    
        if (result.isSuccess()) {    
        // 调用成功    
        }    
});

API 参考: Promotion.showUAShare

import com.hive.Promotion    
    import com.hive.ResultAPI    
    // 邀请消息    
    val invitationMessage = appInvitationData?.inviteMessage ?: ""    
    // 邀请链接    
    val inviteCommonLink = appInvitationData?.inviteCommonLink ?: ""    
    Promotion.showUAShare(invitationMessage, inviteCommonLink, object: Promotion.PromotionShareListener{    
         override fun onPromotionShare(result: ResultAPI) {    
             if (result.isSuccess) {    
                 // 调用成功    
             }    
         }    
})

API 参考: com .hive.Promotion.showUAShare

import com.hive.Promotion;    
    import com.hive.ResultAPI;    
    // 邀请信息    
    String inviteMessage = appInvitationData.getInviteMessage();    
    // 邀请链接    
    String inviteCommonLink = appInvitationData.getInviteCommonLink();    
    Promotion.INSTANCE.showUAShare(inviteMessage, inviteCommonLink, result -> {    
         if (result.isSuccess()) {    
             // 调用成功    
         }    
});

API 参考: PromotionInterface.showUAShare

import HIVEService    
    // 邀请消息    
    let inviteMessage = appInvitationData.inviteMessage    
    // 邀请链接    
    let inviteCommonLink = appInvitationData.inviteCommonLink    
    PromotionInterface.showUAShare(inviteMessage, inviteCommonLink) { result in    
        if result.isSucces() {    
        // 调用成功    
        }    
}

API 参考: HIVEPromotion ::showUAShare:inviteLink:handler:

#import <HIVEService/HIVEService-Swift.h>    
    // 邀请信息    
    NSString *inviteMessage = appInvitationData.inviteMessage;    
    // 邀请链接    
    NSString *inviteCommonLink = appInvitationData.inviteCommonLink;    

    [HIVEPromotion showUAShare: inviteMessage inviteLink: inviteCommonLink handler: ^(HIVEResultAPI *result) {    
         if ([result isSuccess]) {    
            // call successful    
            }    
}];

设计邀请屏幕¶

邀请屏幕显示给用户以邀请朋友加入游戏。利用 qrcode 或 inviteCommonLink 从 AppInvitationData 对象设计邀请屏幕。您可以使用作为 getAppInvitationData() 方法调用结果传递的 AppInvitationData 对象的 qrcode 或 inviteCommonLink 在游戏中实现游戏邀请屏幕。邀请页面没有限制，但以下信息应清楚说明。

一项活动，描述以下内容；邀请必须实现的目标、目标的描述、实现该目标的奖励、邀请完成的次数以及实现目标所需的邀请数量。
一份邀请，描述以下内容；可以邀请的朋友列表，并指定发送实际邀请的方式或程序。

活动和邀请可能根据游戏计划由不同的屏幕组成，或者可能组合在同一个屏幕上。

初始屏幕的示例，使用 inviteCommonLink

建议按照上面示例屏幕中所示显示邀请 URL，并在游戏中设计 UI，以便用户可以将 URL 复制到剪贴板。

设计一个活动屏幕¶

AppInvitationData 类定义了 eachCampaignList 和 stageCampaignList 变量。 eachCampaignList 变量的数据类型是 AppInvitationCampaign 类，而 stageCampaignList 的数据类型是 AppInvitationCampaignState。它们各自包含了活动和活动成就信息。活动屏幕是通过使用以下信息组成的。

AppInvitationCampaign 对象的组成¶

编号	字段名称	描述	类型
1	标题	活动标题	字符串
2	描述	活动描述	字符串
3	imgUrl	活动图标的图片URL	字符串
item	奖励信息（‘key’和‘value’数据类型，采用JSON或HashMap格式。’key’根据活动设置的不同而多样）	Map
4	计数	达成活动的数量	整数
5	限制	活动目标的最大数量	整数
6	目标计数	成就信息（达成所有级别的数量）	整数
-	顺序	活动曝光的顺序	整数
-	campaignId	活动ID（由Hive服务器发出的唯一活动ID）	整数

AppInvitationCampaignStage 对象的组成¶

编号	字段名称	描述	类型
1	标题	活动标题	字符串
2	描述	活动描述	字符串
3	imgUrl	活动图标的图片 URL	字符串
item	奖励信息（‘key’ 和 ‘value’ 数据类型，使用 JSON 或 HashMap 格式。’key’ 根据活动设置的不同而多样）	Map
4	计数	达成活动的数量	整数
5	限制	活动目标的最大数量	整数
6	目标计数	成就信息（达成所有级别的数量）	整数
	目标总数	成就信息（获得奖励所需达成所有级别的数量）	整数
-	顺序	活动曝光的顺序	整数
-	活动 ID	活动 ID（由 Hive 服务器发出的唯一活动 ID）	整数

检查 UA 发送者的信息¶

用户获取发送者的信息现在也可以在客户端 API 中使用。通过点击新用户首次收到的 UA 链接来安装并运行应用程序，然后实现 SDK 初始化和登录。接下来，在 Promotion 类中调用 setEngagementReady(true) 方法。之后，您可以通过调用 getAppInvitationSenderInfo 方法，通过 AppInvitationSenderInfo 对象确认 UA 发送者的信息。

以下是检查UA发送者信息的示例代码。

Unity虚幻引擎C++KotlinJavaSwiftObjective-C

API 参考: Promotion .getAppInvitationSenderInfo

using hive;    
    Promotion.getAppInvitationSenderInfo((result, senderInfo) => {    
        if (!result.isSuccess()) {    
            return;    
        }    
        if (senderInfo != null && !string.IsNullOrEmpty(senderInfo.vid)) {    
        // Successful call and check inviter information    
        }    
});

```c++

include "HivePromotion.h"¶

FHivePromotion::GetAppInvitationSenderInfo(FHivePromotionOnAppInvitationSenderInfoDelegate::CreateLambda(this { if (Result.IsSuccess()) { //Successful call and check inviter information
} }));

API 参考: Promotion ::getAppInvitationSenderInfo

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    Promotion::getAppInvitationSenderInfo([this](ResultAPI result, AppInvitationSenderInfo senderInfo) {    
        if (!result.isSuccess()) {    
        return;    
        }    
        if (senderInfo != NULL && !senderInfo.vid.empty()) {    
        // Successful call and check inviter information    
        }    
});

API 参考: Promotion.getAppInvitationSenderInfo

import com.hive.Promotion    
    import com.hive.ResultAPI    
    Promotion.getAppInvitationSenderInfo(object : Promotion.AppInvitationSenderInfoListener {    
         override fun onAppInvitationSenderInfo(result: ResultAPI, appInvitationSenderInfo: Promotion.AppInvitationSenderInfo?) {    
             if (!result.isSuccess) {    
                 return    
             }    
             if (appInvitationSenderInfo != null && appInvitationSenderInfo.senderVid.isNotEmpty()) {    
                 // Successful call and check inviter information    
             }    
         }    
})

API 参考: Promotion .INSTANCE.getAppInvitationSenderInfo

import com.hive.Promotion;    
    import com.hive.ResultAPI;    
    Promotion.INSTANCE.getAppInvitationSenderInfo((result, appInvitationSenderInfo) -> {    
         if (!result.isSuccess()) {    
             return;    
         }    
         if (appInvitationSenderInfo != null && !(appInvitationSenderInfo.getSenderVid().isEmpty())) {    
             // Successful call and check inviter information    
         }    
});

API 参考: PromotionInterface .getAppInvitationSenderInfo

import HIVEService    
    PromotionInterface.getAppInvitationSenderInfo() { result, senderInfo in    
        if !result.isSuccess() {    
            return    
        }    
        if     
            let senderInfo = senderInfo,            
            let vid = senderInfo.vid, !vid.isEmpty     
        {    
            // Successful call and check inviter information    
        }    
}

API 参考: HIVEPromotion getAppInvitationSenderInfo

#import <HIVEService/HIVEService-Swift.h>    
    [HIVEPromotion getAppInvitationSenderInfo: ^(HIVEResultAPI *result, HiveAppInvitationSenderInfo *senderInfo) {    
         if (![result isSuccess]) {    
             return;    
         }    
        if (senderInfo != nil && [senderInfo.vid length] > 0) {    
        // Successful call and check inviter information    
        }    
}];

AppInvitationSenderInfo 对象的组成¶

编号	字段名称	描述	类型
1	vid	发送者的 vid	字符串

通知 CPA 成就¶

当被邀请的朋友安装游戏或您达到活动目标时，游戏必须通知 Hive 服务器 CPA 成就，以便获得奖励。在给予奖励之前，请确保完成以下工作。

如果两个工作都完成，当达到 CPA 时，调用 CPA 成就通知 API。

什么是用户获取？¶

UA 特性¶

UA 邀请流程¶

注册用户获取活动¶

实施用户获取¶

接收活动信息和邀请 URL/二维码¶

AppInvitationData 对象的组成¶

通过社交媒体分享媒体文件¶

设计邀请屏幕¶

设计一个活动屏幕¶

AppInvitationCampaign 对象的组成¶

AppInvitationCampaignStage 对象的组成¶

检查 UA 发送者的信息¶

include "HivePromotion.h"¶

AppInvitationSenderInfo 对象的组成¶

通知 CPA 成就¶