什麼是用戶獲取？¶

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

邀請的對象不限於 Hive 用戶。每位用戶都會發出一個獨特的邀請網址和二維碼，以識別邀請其他人的用戶。

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

UA 應該為用戶提供易於實現的目標，並給予適當的補償，以增強他們的興趣和參與感。

UA 功能¶

發佈並分享遊戲的邀請網址/二維碼
每次安裝成本 (CPI)，如果朋友安裝了遊戲，則同時獎勵用戶和被邀請的朋友
每次行動成本 (CPA)，如果朋友在玩遊戲時完成了一個任務，則同時獎勵用戶和被邀請的朋友

UA 邀請流程¶

要獎勵，您需要實現項目。

註冊用戶獲取活動¶

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

按計數的成就活動 - 如果被邀請的朋友達成活動目標，則用戶和新朋友都會獲得獎勵
按任務的成就活動 - 如果完成任務的朋友數量達到設定的數字，則用戶和新朋友都會獲得獎勵

有關如何配置活動的更多信息，請參見 Hive 控制台促銷。

實施用戶獲取¶

為遊戲中的UA實施邀請和活動UI，並鼓勵用戶安裝應用程式。

接收活動資訊和邀請網址/QR碼¶

要接收邀請 URL/QR 碼和活動資訊，請在 Promotion 類別中調用 getAppInvitationData() 方法。您可以根據 Hive SDK 中的信息創建邀請頁面或活動畫面。

以下是請求URL/QR碼和Hive SDK的活動資訊的範例代碼。

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/QR 碼一起使用。使用 Hive SDK v4.11.7 中 Promotion 類別提供的 showUAShare() 方法，搭配以下 SNS。

Kakao Talk
LINE
Facebook
Facebook Messenger
WhatsApp
WeChat

使用 Hive SDK v4.11.2 及更高版本但低於 v4.11.7，該功能可以通過在 PlatformHelper 類中使用 shareText() 和 shareMedia() 方法來實現。

Warning

除了上述提到的社交媒體外，還可以實現促銷 API，但 Hive SDK 無法保證其實現。請確保在使用其他類型的社交媒體之前進行測試。
Facebook 不支持分享短文本，只支持網頁 URL 類型。
使用 Facebook 或 LINE 時，使用者無法立即分享媒體。需要額外的操作，點擊註冊/發送按鈕。

安卓
iOS

共享媒體文件僅在文件保存在用戶設備上時可用。要共享網址，請使用文本共享功能或從網址下載文件。以下是通過社交媒體實現文件共享的示例代碼。

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 call success
        }
}));

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 Reference: 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

建議按照上面示例屏幕所示顯示邀請網址，並設計遊戲中的 UI，以便用戶可以將網址複製到剪貼板。

設計一個活動螢幕¶

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	目標計數	成就資訊（完成所有級別的次數）	整數
	目標總數	成就資訊（獲得獎勵所需完成所有級別的數量）	整數
-	順序	活動曝光的順序	整數
-	campaignId	活動 ID（由 Hive 伺服器發出的唯一活動 ID）	整數

檢查 UA 發件人的資訊¶

用戶獲取發送者的信息現在也可以在客戶端 API 中使用。通過點擊新用戶首先收到的 UA 連結來安裝並運行應用程序，然後實現 SDK 初始化和登錄。接下來，在 Promotion 類中調用 setEngagementReady(true) 方法。之後，您可以通過調用 getAppInvitationSenderInfo 方法來確認 UA 發送者的信息，這是通過 AppInvitationSenderInfo 對象完成的。

以下是檢查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()) { //成功的调用并检查邀请者信息
} }));

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 邀請流程¶

註冊用戶獲取活動¶

實施用戶獲取¶

接收活動資訊和邀請網址/QR碼¶

AppInvitationData 物件的組成¶

透過社交媒體分享媒體檔案¶

設計邀請畫面¶

設計一個活動螢幕¶

AppInvitationCampaign 物件的組成¶

AppInvitationCampaignStage 物件的組成¶

檢查 UA 發件人的資訊¶

include "HivePromotion.h"¶

AppInvitationSenderInfo 物件的組成¶

通知 CPA 成就¶