유저 애퀴지션(UA)

유저 애퀴지션(UA)이란?¶

Hive플랫폼에서 제공하는 게임 초대 기능으로, 유저가 자신의 초대 URL 또는 QR코드를 SNS에 공유하여 신규 유저 유입을 유도할 수 있습니다. 이를 통해 초대받은 유저가 게임을 설치하고, 특정 레벨 달성 등과 같은 조건(콘솔에서 조건 및 보상 설정 가능)을 달성했을 때 초대한 유저와 초대받은 유저 모두에게 보상을 제공합니다. 초대의 대상을 Hive 유저로 한정하지 않으며, 초대한 사람이 누구인지 식별할 수 있도록 유니크한 초대 URL과 QR코드를 유저별로 발급합니다.

iOS 유저가 초대 URL을 통해 참여할 경우 다음과 같은 안내페이지를 노출하여 매칭 유실을 방지합니다.

UA는 유저가 쉽게 달성 가능한 목표를 제시하고 그에 적합한 보상을 지급하여, 게임의 흥미와 참여를 높이도록 해야합니다.

기능¶

• 초대 URL/QR 코드 발급 및 공유하기
• 초대 받은 친구가 앱을 설치하면 초대한 유저와 초대받은 친구 둘 다 보상하기 (CPI)
• 초대 받은 친구가 앱 내에서 제안된 목표 달성 시 초대한 유저와 초대받은 친구 둘 다 보상하기 (CPA)

초대 과정¶

UA 캠페인 설정¶

UA 캠페인은 콘솔에서 등록할 수 있습니다. Hive는 다음과 같이 두 종류의 캠페인을 지원합니다.

• 건별 달성 캠페인 - 초대받은 친구가 캠페인 목표를 달성하면 초대한 유저와 초대받은 친구 모두에게 보상하는 캠페인
• 목표 달성 캠페인 - 목표 인원 수를 설정하고, 초대받은 친구들 중 캠페인 목표를 달성한 친구 수가 목표 인원 수를 채우면 초대한 유저와 초대받은 친구 모두에게 보상하는 캠페인

캠페인 설정 방법에 대한 자세한 안내를 보려면 콘솔 프로모션 가이드를 읽어 보세요.

UA 구현하기¶

UA를 구현하기 위해 게임 초대 및 캠페인 UI를 게임에서 구현하고 유저의 앱 설치를 유도합니다.

게임 초대 URL/QR 코드와 캠페인 정보 받기¶

Hive로부터 게임 초대 URL/QR코드와 캠페인 정보를 전달 받으려면, Promotion 클래스의 getAppInvitationData() 메서드를 호출하세요. Hive로부터 해당 정보를 전달받아 초대 페이지를 구성하거나, 캠페인 정보를 전달받아 캠페인 화면을 구성할 수 있습니다.

다음은 게임 초대 URL/QR코드와 캠페인 정보를 Hive에 요청하는 예제 코드입니다.

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 호출 성공
        }
}));

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

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    
             }    
         }    
})

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

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

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

getAppInvitationData() 메서드 호출의 결과로 AppInivitationData라는 오브젝트를 통해 데이터가 전달됩니다.

AppInvitationData 오브젝트의 구성¶

소셜 미디어로 공유하기¶

게임 초대 URL/QR 코드와 캠페인 정보 받기로는 할 수 없었던 소셜 미디어(SNS) 공유 기능을 지원합니다. 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() 메서드로 해당 기능을 이용할 수 있습니다.

Android	iOS

미디어 공유 기능은 단말기에 저장된 파일만 지원합니다. URL을 공유하려면 텍스트 공유 기능을 이용하거나, URL에서 미디어 파일을 다운로드한 후 공유하는 방법이 있습니다. 다음은 SNS 공유 기능을 활용한 예제 코드입니다.

using hive;    
    // invitation message    
    String inviteMessage = appInvitationData.inviteMessage;    
    // invitation link    
    String inviteCommonLink = appInvitationData.inviteCommonLink;    
    Promotion.showUAShare(inviteMessage, inviteCommonLink, (ResultAPI result) => {    
         if (result.isSuccess()) {    
            // call successful    
        }    
});

#include "HivePromotion.h"

FString InviteMessage = TEXT("InviteMessage"); // AppInvitationData.InviteMessage;
FString InviteLink = TEXT("InviteLink"); // AppInvitationData.InviteCommonLink;

FHivePromotion::ShowUAShare(InviteMessage, InviteLink, FHivePromotionOnUAShareDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        }
}));

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    // invitation message    
    string inviteMessage = appInvitationData.inviteMessage.c_str();    
    // invitation link    
    string inviteCommonLink = appInvitationData.inviteCommonLink.c_str();    
    Promotion::showUAShare(inviteMessage, inviteCommonLink, [=](ResultAPI const &result) {    
        if (result.isSuccess()) {    
        // call successful    
        }    
});

import com.hive.Promotion    
    import com.hive.ResultAPI    
    // invitation message    
    val invitationMessage = appInvitationData?.inviteMessage ?: ""    
    // invitation link    
    val inviteCommonLink = appInvitationData?.inviteCommonLink ?: ""    
    Promotion.showUAShare(invitationMessage, inviteCommonLink, object: Promotion.PromotionShareListener{    
         override fun onPromotionShare(result: ResultAPI) {    
             if (result.isSuccess) {    
                 // call successful    
             }    
         }    
})

import com.hive.Promotion;    
    import com.hive.ResultAPI;    
    // invitation message    
    String inviteMessage = appInvitationData.getInviteMessage();    
    // invitation link    
    String inviteCommonLink = appInvitationData.getInviteCommonLink();    
    Promotion.INSTANCE.showUAShare(inviteMessage, inviteCommonLink, result -> {    
         if (result.isSuccess()) {    
             // call successful    
         }    
});

import HIVEService    
    // invitation message    
    let inviteMessage = appInvitationData.inviteMessage    
    // invitation link    
    let inviteCommonLink = appInvitationData.inviteCommonLink    
    PromotionInterface.showUAShare(inviteMessage, inviteCommonLink) { result in    
        if result.isSucces() {    
        // call successful    
        }    
}

#import <HIVEService/HIVEService-Swift.h>    
    // invitation message    
    NSString *inviteMessage = appInvitationData.inviteMessage;    
    // invitation link    
    NSString *inviteCommonLink = appInvitationData.inviteCommonLink;    

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

게임 초대 화면 구성하기¶

초대 화면은 게임 내 친구 초대 기능이 유저에게 보여지는 화면입니다. getAppInvitationData() 메서드 호출의 결과로 전달받은 AppInivitationData라는 오브젝트의 qrcode 또는 inviteCommonLink를 이용하여 게임에서는 게임 초대 화면을 구현할 수 있습니다. 초대 화면은 자유롭게 구성이 가능하지만 아래 사항이 명확히 명시되어야 합니다.

• 초대를 통해 달성해야 하는 목표, 해당 목표에 대한 설명, 해당 목표를 달성함으로써 얻을 수 있는 보상, 초대가 완료된 횟수, 목표를 달성하기 위해 필요한 초대 횟수 등이 명시된 캠페인
• 초대 발송이 가능한 친구 리스트를 표시 하고, 실제 초대 발송을 할 수 있는 방법이나 절차를 명시한 초대 발송

캠페인과 초대 발송은 게임 기획에 따라 서로 다른 화면으로 구성되거나, 같은 화면에 함께 구성될 수도 있습니다.

• inviteCommonLink를 이용한 게임 초대 화면 예시 예시 화면과 같이 초대 URL을 노출하고 클립보드로 복사할 수 있도록 게임에서 UI를 구성하는 것을 권장합니다.

캠페인 화면 구성하기¶

위에서 설명한 AppInvitationData 클래스에는 eachCampaignList와 stageCampaignList 변수를 정의합니다. eachCampaignList 변수의 데이터 형은 AppInvitationCampaign 클래스, stageCampaignList 변수의 데이터 형은 AppInvitationCampaignStage 클래스이며, 각각 캠페인 정보와 캠페인 달성도 정보를 담고 있습니다. 캠페인 화면은 이 정보를 이용하여 구성할 수 있습니다.

AppInvitationCampaign 오브젝트의 구성¶

AppInvitationCampaignStage 오브젝트의 구성¶

UA 초대자 정보 확인하기¶

Hive Server API에서 제공되던 UA 초대자 정보 서버 API를 이제 클라이언트 API로도 제공합니다.

먼저, 신규 유저는 초대받은 UA 링크를 클릭하여 앱 설치 및 실행합니다. 이후, SDK 초기화 구현 및 로그인을 진행하고 Promotion 클래스의 setEngagementReady(true) 메서드를 호출하십시오. 메서드 호출이 완료되면 getAppInvitationSenderInfo 메서드를 호출하여 AppInvitationSenderInfo 객체를 통해 초대자 정보를 확인할 수 있습니다.

다음은 UA 초대자 정보를 확인하는 예제 코드입니다.

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

#include "HivePromotion.h"

FHivePromotion::GetAppInvitationSenderInfo(FHivePromotionOnAppInvitationSenderInfoDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveAppInvitationSenderInfo& AppInvitationSenderInfo) {
        if (Result.IsSuccess()) {
                // API 호출 성공
                // AppInvitationSenderInfo 응답값을 통해 초대자 정보 확인
        }
}));

#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    
        }    
});

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    
             }    
         }    
})

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

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    
        }    
}

#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 오브젝트의 구성¶

CPA 달성 알림¶

초대받은 친구가 게임을 설치했을 때 보상을 지급하고, 캠페인의 목표를 달성할 때 보상을 지급하려면 게임 앱이 Hive 서버에 CPA 달성을 알려야 합니다. CPA 달성 시 보상 지급 구현하기 위해 다음 2가지 작업이 선행되야 합니다.

• Hive 콘솔에 설정한 CPA 캠페인 달성 시 보상 지급을 하도록 설정
• Hive 아이템 연동

위 두 가지 작업이 완료되었다면 CPA 달성 시 CPA 달성 알림 API를 호출하세요.