유저 애퀴지션(UA)이란?
Hive에서 제공하는 게임 초대 기능으로, 유저가 자신의 초대 URL 또는 QR코드를 SNS에 공유하여 신규 유저 유입을 유도할 수 있습니다. 이를 통해 초대받은 유저가 게임을 설치하고, 특정 레벨 달성 등과 같은 조건(Hive 콘솔에서 조건 및 보상 설정 가능)을 달성했을 때 초대한 유저와 초대받은 유저 모두에게 보상을 제공합니다.
초대의 대상을 Hive 유저로 한정하지 않으며, 초대한 사람이 누구인지 식별할 수 있도록 유니크한 초대 URL과 QR코드를 유저별로 발급합니다.
iOS 유저가 초대 URL을 통해 참여할 경우 다음과 같은 안내페이지를 노출하여 매칭 유실을 방지합니다.
UA는 유저가 쉽게 달성 가능한 목표를 제시하고 그에 적합한 보상을 지급하여, 게임의 흥미와 참여를 높이도록 해야합니다.
기능
- 초대 URL/QR 코드 발급 및 공유하기
- 초대 받은 친구가 앱을 설치하면 초대한 유저와 초대받은 친구 둘 다 보상하기 (CPI)
- 초대 받은 친구가 앱 내에서 제안된 목표 달성 시 초대한 유저와 초대받은 친구 둘 다 보상하기 (CPA)
초대 과정
UA 보상을 위해서는 Hive 아이템 적용이 필요합니다.
UA 캠페인 설정
UA 캠페인은 Hive 콘솔에서 등록할 수 있습니다. Hive는 다음과 같이 두 종류의 캠페인을 지원합니다.
- 건별 달성 캠페인 – 초대받은 친구가 캠페인 목표를 달성하면 초대한 유저와 초대받은 친구 모두에게 보상하는 캠페인
- 목표 달성 캠페인 – 목표 인원 수를 설정하고, 초대받은 친구들 중 캠페인 목표를 달성한 친구 수가 목표 인원 수를 채우면 초대한 유저와 초대받은 친구 모두에게 보상하는 캠페인
캠페인 설정 방법에 대한 자세한 안내를 보려면 Hive 콘솔 프로모션 가이드를 읽어 보세요.
UA 구현하기
UA를 구현하기 위해 게임 초대 및 캠페인 UI를 게임에서 구현하고 유저의 앱 설치를 유도합니다.
게임 초대 URL/QR 코드와 캠페인 정보 받기
Hive로부터 게임 초대 URL/QR코드와 캠페인 정보를 전달 받으려면, Promotion 클래스의 getAppInvitationData() 메서드를 호출하세요. Hive로부터 해당 정보를 전달받아 초대 페이지를 구성하거나, 캠페인 정보를 전달받아 캠페인 화면을 구성할 수 있습니다.
다음은 게임 초대 URL/QR코드와 캠페인 정보를 Hive에 요청하는 예제 코드입니다.
API Reference: hive.Promotion.getAppInvitationData
|
1 2 3 4 5 6 7 |
using hive; Promotion.getAppInvitationData((ResultAPI result, AppInvitationData appInvitationData) => { if (result.isSuccess()) { // 호출 성공 } }); |
API Reference: Promotion::getAppInvitationData
|
1 2 3 4 5 6 7 8 9 |
#include <HIVE_SDK_Plugin/HIVE_CPP.h> using namespace std; using namespace hive; Promotion::getAppInvitationData([=](ResultAPI result, AppInvitationData appInvitationData) { if (result.isSuccess()) { // 호출 성공 } }); |
API Reference: Promotion.getAppInvitationData
|
1 2 3 4 5 6 7 8 9 10 |
import com.hive.Promotion import com.hive.ResultAPI Promotion.getAppInvitationData(object : Promotion.AppInvitationDataListener { override fun onAppInvitationData(result: ResultAPI, appInvitationData: Promotion.AppInvitationData?) { if (result.isSuccess) { // 호출 성공 } } }) |
API Reference: com.hive.Promotion.getAppInvitationData
|
1 2 3 4 5 6 7 8 |
import com.hive.Promotion; import com.hive.ResultAPI; Promotion.INSTANCE.getAppInvitationData((result, appInvitationData) -> { if (result.isSuccess()) { // 호출 성공 } }); |
API Reference: PromotionInterface.getAppInvitationData
|
1 2 3 4 5 6 7 |
import HIVEService PromotionInterface.getAppInvitationData() { result, appInvitationData in if result.isSuccess() { // 호출 성공 } } |
API Reference: HIVEPromotion:getAppInvitationData
|
1 2 3 4 5 6 7 |
#import <HIVEService/HIVEService-Swift.h> [HIVEPromotion getAppInvitationData: ^(HIVEResultAPI *result, HIVEAppInvitationData *appInvitationData) { if ([result isSuccess]) { // 호출 성공 } }]; |
getAppInvitationData() 메서드 호출의 결과로 AppInivitationData라는 오브젝트를 통해 데이터가 전달됩니다.
AppInvitationData 오브젝트의 구성
| 필드명 | 설명 | 타입 |
| qrcode | 앱의 초대 정보가 포함된 QR Code 이미지 데이터 (비트맵 이미지를 HEXA 문자열 형태로 저장) |
String |
| inviteMessage | 앱 초대 문구 | String |
| inviteCommonLink | 앱 초대 링크 | String |
| inviteHivemsgLink | Hive 메시지 기능을 통해 전달하는 앱 초대 링크 | String |
| eachCampaignList | 캠페인 완료 발생시, 매번 보상을 지급하는 캠페인 목록 | AppInvitationCampaign 리스트 |
| stageCampaignList | 캠페인 완료 목표 초대 수를 달성했을 때 보상을 지급하는 캠페인 목록 | AppInvitationCampaignStage 리스트 |
소셜 미디어로 공유하기
게임 초대 URL/QR 코드와 캠페인 정보 받기로는 할 수 없었던 소셜 미디어(SNS) 공유 기능을 지원합니다. Hive SDK v4.11.7부터 Promotion 클래스 showUAShare() 메서드를 활용할 수 있으며, 지원하는 SNS는 아래와 같습니다.
- Kakao Talk
- LINE
- Facebook Messenger
Hive SDK v4.11.2 이상 v4.11.7 미만은 PlatformHelper 클래스의 shareText() 메서드와 shareMedia() 메서드로 해당 기능을 이용할 수 있습니다.
 |
 |
미디어 공유 기능은 단말기에 저장된 파일만 지원합니다. URL을 공유하려면 텍스트 공유 기능을 이용하거나, URL에서 미디어 파일을 다운로드한 후 공유하는 방법이 있습니다. 다음은 SNS 공유 기능을 활용한 예제 코드입니다.
API Reference: hive.Promotion.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 |
using hive; // 초대 메세지 String inviteMessage = appInvitationData.inviteMessage; // 초대 링크 String inviteCommonLink = appInvitationData.inviteCommonLink; Promotion.showUAShare(inviteMessage, inviteCommonLink, (ResultAPI result) => { if (result.isSuccess()) { // 호출 성공 } }); |
API Reference: Promotion::showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
#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 Reference: Promotion.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
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 Reference: com.hive.Promotion.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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 Reference: PromotionInterface.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
#import <HIVEService/HIVEService-Swift.h> // 초대 메세지 NSString *inviteMessage = appInvitationData.inviteMessage; // 초대 링크 NSString *inviteCommonLink = appInvitationData.inviteCommonLink; [HIVEPromotion showUAShare: inviteMessage inviteLink: inviteCommonLink handler: ^(HIVEResultAPI *result) { if ([result isSuccess]) { // 호출 성공 } }]; |
게임 초대 화면 구성하기
초대 화면은 게임 내 친구 초대 기능이 유저에게 보여지는 화면입니다. getAppInvitationData() 메서드 호출의 결과로 전달받은 AppInivitationData라는 오브젝트의 qrcode 또는 inviteCommonLink를 이용하여 게임에서는 게임 초대 화면을 구현할 수 있습니다. 초대 화면은 자유롭게 구성이 가능하지만 아래 사항이 명확히 명시되어야 합니다.
- 초대를 통해 달성해야 하는 목표, 해당 목표에 대한 설명, 해당 목표를 달성함으로써 얻을 수 있는 보상, 초대가 완료된 횟수, 목표를 달성하기 위해 필요한 초대 횟수 등이 명시된 캠페인
- 초대 발송이 가능한 친구 리스트를 표시 하고, 실제 초대 발송을 할 수 있는 방법이나 절차를 명시한 초대 발송
캠페인과 초대 발송은 게임 기획에 따라 서로 다른 화면으로 구성되거나, 같은 화면에 함께 구성될 수도 있습니다.
inviteCommonLink를 이용한 게임 초대 화면 예시
예시 화면과 같이 초대 URL을 노출하고 클립보드로 복사할 수 있도록 게임에서 UI를 구성하는 것을 권장합니다.
캠페인 화면 구성하기
위에서 설명한 AppInvitationData 클래스에는 eachCampaignList와 stageCampaignList 변수를 정의합니다. eachCampaignList 변수의 데이터 형은 AppInvitationCampaign 클래스, stageCampaignList 변수의 데이터 형은 AppInvitationCampaignStage 클래스이며, 각각 캠페인 정보와 캠페인 달성도 정보를 담고 있습니다. 캠페인 화면은 이 정보를 이용하여 구성할 수 있습니다.
AppInvitationCampaign 오브젝트의 구성
| 번호 | 필드명 | 설명 | 타입 |
| 1 | title | 캠페인 제목 | String |
| 2 | description | 캠페인 설명 | String |
| 3 | imgUrl | 캠페인 아이콘 이미지 URL | String |
| item | 완료 보상 정보(JSON 이나 HashMap 형태의 ‘key’ / ‘value’ 자료형, ’key’는 캠페인 설정에 따라 상이함) | Map<key, value> | |
| 4 | count | 캠페인 조건 달성 건수 | Integer |
| 5 | limit | 캠페인 최대 인원 수 | Integer |
| – | order | 캠페인 순서 | Integer |
| – | campaignId | 캠페인 아이디(Hive 서버에서 발급한 캠페인 고유 아이디) | Integer |
AppInvitationCampaignStage 오브젝트의 구성
| 번호 | 필드명 | 설명 | 타입 |
| 1 | title | 캠페인 제목 | String |
| 2 | description | 캠페인 설명 | String |
| 3 | imgUrl | 캠페인 아이콘 이미지 URL | String |
| item | 완료 보상 정보(JSON 이나 HashMap 형태의 ‘key’ / ‘value’ 자료형, ’key’는 캠페인 설정에 따라 상이함) | Map<key, value> | |
| 4 | count | 캠페인 조건 달성 건수 | Integer |
| 5 | limit | 캠페인 최대 인원 수 | Integer |
| 6 | goalCount | 목표 달성 정보(모든 단계를 완료한 인원 수) | Integer |
| goalTotal | 목표 달성 정보(보상을 받기 위해 모든 단계를 완료해야 하는 인원 수) | Integer | |
| – | order | 캠페인 순서 | Integer |
| – | campaignId | 캠페인 아이디(Hive 서버에서 발급한 캠페인 고유 아이디) | Integer |
UA 초대자 정보 확인하기
Hive Server API에서 제공되던 UA 초대자 정보 서버 API를 이제 클라이언트 API로도 제공합니다.
먼저, 신규 유저는 초대받은 UA 링크를 클릭하여 앱 설치 및 실행합니다. 이후, SDK 초기화 구현 및 로그인을 진행하고 Promotion 클래스의 setEngagementReady(true) 메서드를 호출하십시오. 메서드 호출이 완료되면 getAppInvitationSenderInfo 메서드를 호출하여 AppInvitationSenderInfo 객체를 통해 초대자 정보를 확인할 수 있습니다.
다음은 UA 초대자 정보를 확인하는 예제 코드입니다.
API Reference: Promotion.getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 |
using hive; Promotion.getAppInvitationSenderInfo((result, senderInfo) => { if (!result.isSuccess()) { return; } if (senderInfo != null && !string.IsNullOrEmpty(senderInfo.vid)) { // 호출 성공 및 초대자 정보 확인 } }); |
API Reference: Promotion::getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
#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()) { // 호출 성공 및 초대자 정보 확인 } }); |
API Reference: Promotion.getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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()) { // 호출 성공 및 초대자 정보 확인 } } }) |
API Reference: Promotion.INSTANCE.getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 |
import com.hive.Promotion; import com.hive.ResultAPI; Promotion.INSTANCE.getAppInvitationSenderInfo((result, appInvitationSenderInfo) -> { if (!result.isSuccess()) { return; } if (appInvitationSenderInfo != null && !(appInvitationSenderInfo.getSenderVid().isEmpty())) { // 호출 성공 및 초대자 정보 확인 } }); |
API Reference: PromotionInterface.getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
import HIVEService PromotionInterface.getAppInvitationSenderInfo() { result, senderInfo in if !result.isSuccess() { return } if let senderInfo = senderInfo, let vid = senderInfo.vid, !vid.isEmpty { // 호출 성공 및 초대자 정보 확인 } } |
API Reference: HIVEPromotion getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 |
#import <HIVEService/HIVEService-Swift.h> [HIVEPromotion getAppInvitationSenderInfo: ^(HIVEResultAPI *result, HiveAppInvitationSenderInfo *senderInfo) { if (![result isSuccess]) { return; } if (senderInfo != nil && [senderInfo.vid length] > 0) { // 호출 성공 및 초대자 정보 확인 } }]; |
AppInvitationSenderInfo 오브젝트의 구성
| 번호 | 필드명 | 설명 | 타입 |
| 1 | vid | 초대자의 vid | String |
CPA 달성 알림
초대받은 친구가 게임을 설치했을 때 보상을 지급하고, 캠페인의 목표를 달성할 때 보상을 지급하려면 게임 앱이 Hive 서버에 CPA 달성을 알려야 합니다. CPA 달성 시 보상 지급 구현하기 위해 다음 2가지 작업이 선행되야 합니다.
위 두 가지 작업이 완료되었다면 CPA 달성 시 CPA 달성 알림 API를 호출하세요.