주의 사항

UA 사용 시, 로그인 이후 반드시 Promotion_Acquisition의 Data Request를 한번 호출하여야 한다.
이 함수 호출을 통해 해당 유저가 URL을 통해 게임 설치 및 실행을 하였는지 플랫폼 서버에서 판단할 수 있다.

 

UA

UA(User Acquisition)는 플랫폼에서 제공하는 친구 초대 기능이다.
유저 개인별 초대 URL을 발급하고, 친구가 해당 URL을 통해 게임 설치 및 실행과 CPA 달성까지, 플랫폼에서 트래킹 후 정상적으로 완료된 건에 한해 보상을 지급한다.
(CPA의 경우 게임서버에서 달성 로그를 UA 서버로 전송 필요)

 

초대 과정

 

이점

항목 AS IS UA
초대 가능 범위 나와 Hive 친구인 유저 중 해당 게임을 플레이 하지 않는 유저 모든 유저 (Hive 비회원도 가능)
초대 방법 UID로 트래킹하기 때문에 친구마다 초대 발송하고 수락 필요 초대 뿐만 아니라 블로그, 담벼락 등에 초대 URL을 게시해 홍보가 가능하고,
초대를 직접 받지 않은 유저도 해당 URL을 통하면 초대 달성 가능

 

제한 사항

  • 적용 가능한 Hive SDK 버전
    Hive SDK v1.9.0 이상

– 사용 가능한 OS 버전
Android 2.3.3 이상
iOS 6 이상

– 초대 보상을 위해 Hive 아이템 적용 필요 

 

초대 성립 정보

트래킹 방법
iOS version 9 이상
(개인정보보호 모드 OFF)
초대 코드(초대 URL중 유저 개인의 고유 번호)와 참여 ID를 사파리 브라우저에서 쿠키로 저장해 놓으면 게임 실행 시 게임 내 브 라우저에서 저장된 쿠키를 읽은 후 UA 서버로 전달하고, UA 서버는 전달받은 초대 코드와 참여 ID로 초대 성립 여부 판단
iOS 8 이하
iOS 9 이상
(개인정보보호 모드 ON)
중국 IP의 Android
초대 URL 클릭 시 랜딩 페이지에서 수집한 UserAgent(IP, OS 버전, 단말 모델명)가 게임 실행 시 정보와 모두 일치하는지 확인
Android 마켓 이동 시 리퍼러를 통해 설치될 게임으로 초대 정보 전송
UA 초대 성립 가능 상황
트래킹이 누락된 것 없이 완벽히 이루어진 경우
초대받은 유저 기준 참여 DID가 해당 게임의 Acquisition 성립 기록이 없는 경우
초대받은 유저 기준 해당 게임의 VID가 Acquisition 성립 기록이 없는 경우
초대받은 유저단말 기준 해당 게임을 최초설치 또는 최초설치시점부터 7일 이내 재설치일 경우
랜딩 URL 클릭시점과 게임실행시점이 7일이내인 경우
예상되는 예외 상황
iOS 및 중국 Android 초대 URL 클릭시 UserAgent와 게임 설치시 단말 모델명이 다를 경우 (아래 iOS 단말 모델명 추출방식 참고)
→ 자사 QA에서 구비한 단말들로 테스트를 해보며 동일하게 수집됨을 확인하였으나, 다른 정보로 수집이 될 가능성 존재
에뮬레이터 등을 통해 초대받는 유저의 VID와 DID를 무한정 생성시 보상 제한 수 만큼 보상 지급 (받을 수 있는 최대 보상 횟수 제한 필요)
  • iOS 단말 모델 명 추출 방식
    설치 시 추출한 UserAgent는 브라우저에서 추출한 UserAgent와는 다른 양식으로 구성되어 있어 모델 명을 수집할 수 없음
    랜딩 페이지에서 수집하는 모델명은 UserAgent를 통해 수집하고, 설치 시 수집하는 모델명은 AU 클라이언트 모듈에서 직접 수집한 단말 정보를 이용
    현재는 ipad, ipod, iphone 3가지로 분류하여 체크

 

초대 URL 랜딩 페이지 플로우

 

적용가이드

초대

 

초대 화면

초대 화면은 게임 내 친구 초대 기능이 유저에게 나타나는 화면이다.
초대 화면은 자유롭게 구성이 가능하지만 아래 사항이 명시되어야 한다.

1) 초대를 통해 달성해야 하는 목표, 해당 목표에 대한 설명, 해당 목표를 달성함으로써 얻을 수
있는 보상, 초대가 완료된 횟수, 목표를 달성하기 위해 필요한 초대 횟수 등이 명시된 캠페인

2) 초대 발송이 가능한 친구 리스트를 표시 하고, 실제 초대 발송을 할 수 있는 방법이나 절차를
명시한 초대 발송

캠페인과 초대 발송은 서로 다른 화면으로 구성되거나, 같은 화면에 함께 구성될 수도 있다.
(아래 초대 화면 예시 참고)

초대 화면 예시

 

초대 화면 구성

API 참조 – C2SModulePromotion_Acquisition  

Result – Api.Promotion_Acquisition

콜백으로 개인별 초대 URL, QR code, 백오피스에 설정된 CPA data정보가 전달된다.
type = “qrcodeShare”, “linkShare” 이면 콜백이 없다.
type = “qrcodeSave” 이면 v1.19.0.2 부터 QRCode 사진 저장 기능이 제거되어 “Not Supported API”의 에러 콜백이 전달된다.

name type desc
inviteCommonLink string 기본 초대 링크
inviteHivemsgLink string Hive 메시지용 초대 링크
qrcode hex string QR code 이미지 데이터
eachCampaigns array 캠페인 완료 발생 시, 매번 보상을 지급하는 캠페인 목록
stageCampaigns array 캠페인 완료 목표 초대 수에 도달했을 때, 보상을 지급하는 캠페인 목록

 

array eachCampaigns and stageCampaigns

argument name type desc
title string 캠페인 타이틀
desc string 캠페인 설명
imgUrl string 캠페인 이미지 URL
item dictionary 완료 보상 정보
(‘key’는 캠페인 설정에 설정한 Hive 아이템 종류)
count int 초대 인원 중, 캠페인을 완료한 수
limit int 캠페인 최대 인원 수
order int 캠페인 노출 순서
campaignId int 캠페인 아이디(Hive 서버에서 발급한 캠페인 고유 아이디)

 

초대 화면 데이타 요청 API

1) 개인별 초대 URL, QR code, 백오피스에 설정된 CPA 데이타를 전달받아 캠페인 페이지와 초대 페이지를 구성할 수 있다.
2) OS SDK에서 제공하는 기본 공유 수단으로 초대 URL과 QR code를 간 편히 공유하는 기능을 제공한다.
(OS 기본 공유 수단 – 아래 내용 참고)
3) QR code를 사진첩에 저장하는 기능을 제공한다.

 

외부 저장소 퍼미션 설정 (OS 버전에 상관없이 추가 필요)

– Android에서 QR code 공유 / 저장 기능을 사용하기 위해서는 AndroidManifest.xml에 외부저장소 사용
퍼미션 설정이 필요
– 퍼미션 설정 : < uses-permission android:name=”android.permission.WRITE_EXTERNAL_STORAGE” />

 

Android 6.0 이상 단말에서 유저의 외부저장소 퍼미션 거부 이슈

1) 유저가 외부저장소 퍼미션을 거부한 경우 QR code를 사진첩에 저장하는 기능을 사용할 수 없음
2) 외부 저장소 퍼미션을 거부한 유저가 QRcode 저장 액션을 실행한 경우 별도의 안내창을 통해 퍼미션을 수락이 필요함을 안내 (아래 예시 참고)
3) 퍼미션을 거부한 상태의 유저가 실행한 에러 정보
에러 메시지 : permission denied
에러코드 : -99

캠페인

클라이언트 API 호출, 응답 부분 샘플 코드

Campaign Data
No. name type desc
 1 title string 캠페인 타이틀
 2 desc string 캠페인 설명
 3 imgUrl string 캠페인 이미지 URL
item dictionary 완료 보상 정보
(key는 캠페인 설정에 설정한 Hive 아이템 종류)
 4 count int 초대 인원 중, 캠페인을 완료한 수
 5 limit int 캠페인 최대 인원 수
6 order int 캠페인 노출 순서
campaignId int 캠페인 아이디 (Hive 서버에서 발급한 캠페인 고유 아이디)

 

클라이언트 캠페인 구성 API 샘플 코드

Unity3D

 

Unreal

 

iOS

 

Cocos2d-x

 

CPA

 

1) 설명

  • UA에서 게임서버와 CPA를 연동하기 위한 API
  • 게임서버에서 특정 목표 달성 시 CPA 코드와 함께 유저 정보를 UA 서버로 전송

2) 연동

  • UA 백오피스 → CPA 관리에서 CPA 코드 발급 (UA 운영 담당자와 확인)
  • 아래 API 스펙에 맞춰 데이터 전송

3) API 스펙

 

 

프로모션 애퀴지션

Hive Server API에서 제공되던 UA 초대자 정보 서버 API를 이제 클라이언트 API로도 제공한다.
먼저, 초대받은 UA 링크를 클릭하여 앱 설치 및 실행한다. 이후, SDK 초기화 구현 및 로그인을 진행하고 C2SModuleEngagement_SetReady API 호출이 완료되면 key-value 객체를 통해 초대자 정보를 확인할 수 있다.

C2SModulePromotion_Acquisition

개인별 초대 URL, QR code, 백오피스에 설정된 CPA 데이타를 전달받아 캠페인 페이지와 초대 페이지를 구성할 수 있다. (Hive SDK v1.9.0+)
OS SDK에서 제공하는 기본 공유 수단으로 초대 URL과 QR code를 간편히 공유하는 기능을 제공한다.
QR code를 사진첩에 저장하는 기능을 제공한다.
type = “qrcodeShare”, “linkShare” 이면 콜백이 없다.
type = “qrcodeSave” 이면 v1.19.0.2 부터 QRCode 사진 저장 기능이 제거되어 “Not Supported API”의 에러 콜백이 전달된다.

Hive SDK v1.12.0 버전부터 기존의 식별자 파라미터가 삭제되고 통합 식별자로 통일되었다.

현재 사용중인 통합 식별자 gameWorld와 gameLanguage는 아래 API에서 설정 가능하다.

– C2SModuleSocial_Initialize
– C2SModuleSocial_SetGameInfo

argument name type desc platform 비고
 1. Acquisition Data Request
gameWorld string 게임 서버 ID
서버 지역 코드값은 ‘ISO 3166 alpha-2’ 코드를 기준으로 하며 Hive 연동 가이드라인 게임서버 ID 항목을 참고한다.
all (1.12.0+ 삭제)
gameLanguage string 게임 언어
(default : 단말의 언어)
게임 언어 코드값은 ‘ISO 639 alpha-2′(ISO 639-1) 코드를 기준으로 하며 Hive 연동 가이드라인 언어 항목을 참고한다.
all Optional
(1.12.0+ 삭제)
 2. QR code 공유 
type string “qrcodeShare” all
data hex string 1. Acquisition Data Request 요청으로 얻은 ‘qrcode’ all
 3. 초대 URL 공유 (inviteCommonLink)
type string “linkShare” all
url string 1. Acquisition Data Request 요청으로 얻은 ‘inviteCommonLink’ all
message string url과 함께 표시되는 메시지 (Optional) (1.10.3+) all 1.10.3+

        

Result – Api.Promotion_Acquisition

콜백으로 개인별 초대 URL, QR code, 백오피스에 설정된 CPA 데이타 정보가 전달된다.
type = “qrcodeShare”, “linkShare” 이면 콜백이 없다.
UA 링크를 통해 앱 설치 및 실행 후 SDK 초기화, 로그인, C2SModuleEngagement_SetReady 호출 단계가 완료되면 type=”senderInfo”로 설정하여 Acquisition API 호출 시 초대자 정보가 반환된다.

argument name type desc platform 비고
inviteCommonLink string 기본 초대 링크 all
inviteHivemsgLink string Hive 메시지(C2SModuleSns_Message)용 초대 링크 all
qrcode hex string QR code 이미지 데이터 all
eachCampaigns array 캠페인 완료 발생 시, 매번 보상을 지급하는 캠페인 목록
(‘key’는 아래에서 확인 가능)
all
stageCampaigns array 캠페인 완료 목표 초대 수에 도달했을 때, 보상을 지급하는 캠페인 목록
(‘key’는 아래에서 확인 가능)
all
senderVid string 초대자의 vid all

 

array eachCampaigns and stageCampaigns

argument name type desc platform 비고
title string 캠페인 타이틀 all
desc string 캠페인 설명 all
imgURL string 캠페인 이미지 URL all
item dictionary 완료 보상 정보
(‘key’는 캠페인 설정에 설정한 Hive 아이템 종류)
all
count int 초대 인원 중, 캠페인을 완료한 수 all
limit int 캠페인 최대 인원 수 all
order int 캠페인 노출 순서 all
campaignId int 캠페인 아이디 (Hive 서버에서 발급한 캠페인 고유 아이디) all

 

샘플 코드

 

Unity3d:C2SModule.Promotion.Acquisition
public static bool C2SModule.Promotion.Acquisition(C2SModule.Parameter arg, out C2SModule.Error error);
public static bool C2SModule.Promotion.Acquisition(C2SModule.Parameter arg, out C2SModule.Error error,
C2SModule.CompletionHandler completionHandler);
Overview

– 콜백으로 초대 URL, QR code, 백오피스에 설정된 CPA 데이타가 전달된다.
type = “qrcodeShare”, “linkShare”일 경우엔 콜백이 오지 않는다.

 

Unreal:HiveSDKUEPromotion_Acquisition
void HiveSDKUETracker_SendEvent(FString fstrJson);
Overview

– 콜백으로 초대 URL, QR code, 백오피스에 설정된 CPA 데이타가 전달된다.
type = “qrcodeShare”, “linkShare”일 경우엔 콜백이 오지 않는다.

 

IOS:C2SModulePromotion Acquisition
+(BOOL)Acquisition:(id)arg error:(NSError**)error;
+(BOOL)Acquisition:(id)arg error:(NSError**)error completionHandler:(void(^)(NSDictionary *, NSError*))
completionHandler;
Overview

– 콜백으로 초대 URL, QR code, 백오피스에 설정된 CPA 데이타가 전달된다.
type = “qrcodeShare”, “linkShare”일 경우엔 콜백이 오지 않는다.

 

Cocos2d-x:C2SModulePromotion_Acquisition
bool C2SModulePromotion_Acquisition(const char* pstrJson, C2SModule_Cocos2dx::C2SModuleError* pkError,
C2SModule_Cocos2dx::C2SModuleCompletionHandler* completionHandler = NULL);
Overview

– 콜백으로 초대 URL, QR code, 백오피스에 설정된 CPA 데이타가 전달된다.
type = “qrcodeShare”, “linkShare”일 경우엔 콜백이 오지 않는다.