Mercury 모듈 적용 가이드 (Unity3d)

Com2uS 공통모듈

>>

Mercury

>>

Mercury 모듈 적용 가이드 (iOS)

Mercury 모듈 적용 가이드 (Android)

Mercury 모듈 적용 가이드 (Unity3d)

>>

Mercury 모듈 레퍼런스 가이드

>>

Mercury FAQ

공통 유의 사항

<작성법 참고>

Mercury적용 시 유의 사항

Mercury 모듈 적용 시에는 Chartboost와 NewsBanner2를 적용하지 않음
Mercury 에서 NewsBanner2를 함께 노출하고 있기 때문에 함께 적용하지 않음
Mercury 전 후로 Chartboost가 함께 뜨는 것을 방지하기 위하여 Chartboost는 광고주로만 적용한다

Active User -> Hive Login -> Mercury 초기화 및 SetUID 설정 순서로 모듈이 실행되도록 적용한다
위 순서로 하지 않으면 Mercury관련 서버에 UID Log가 남지 않는다

<작성법 참고>

App ID 등록

앱 아이디, 노출 여부, 노출시킬 배너를 백오피스에 등록해야 합니다.
- 앱 정보를 등록하지 않을 경우 배너가 노출되지 않습니다.

<작성법 참고>

UI제작 필요

Mercury 공지사항 노출 함수(ShowNotice)를 사용하기 위한 버튼 UI제작이 필요합니다.

<작성법 참고>

함수호출 위치

CS_MercuryShowForNotice와 CS_MercuryForcedShowForNotice 함수가 호출되는 위치는 같은 Scene에서 이루어지도록 해야 합니다.

CS_MercuryShowForEvent와 CS_MercuryForcedShowForEvent 함수도 동일합니다.

<작성법 참고>

서버 에러 로그

서버에서 미노출 상태에 대한 에러로그를 클라이언트 로그로 출력하고 있습니다. 해당 로그들을 확인하고 문의하면 좀 더 빠른 답변을 얻으실 수 있습니다.
- error number : 0, msg : success => 성공
- error number : 1, msg : post data is null => 클라이언트로부터 받은 post 데이터가 없음
- error number : 2, msg : some data are missing => App ID, language, action 의 중요한 정보가 없음
- error number : 3, msg : cannot find mercury main info => 머큐리 메인 정보를 찾을 수 없음 : App ID 미등록일 확률이 높음.
- error number : 5, msg : cannot find cpi/event info => 전면배너에 등록될 이벤트나 CPI정보가 없음: 웹뷰개수가 1개이고 전면배너만 노출하도록 설정했을 경우.

<작성법 참고>

YouTube 동영상 프로모션 (Android & iOS Mercury v2.11.0+)

YouTube 동영상 링크가 담긴 스키마를 프로모션 페이지의 링크로 설정하여 Mercury에서 재생 가능
- 스키마 형태

c2smercury://videoplay?{pid}|{time_to_show_close_btn}|{time_to_remain_close_btn}|{URL}

// ex ) c2smercury://videoplay?200001|4|2|https://www.youtube.com/watch?v=0gIOjN_kmKc
// - pid : 프로모션
// - time_to_show_close_btn : 동영상 종료 버튼 최초 노출 시간(sec)
// - time_to_remain_close_btn : 종료 버튼 노출 시 화면에 유지 시간(sec)
// - URL : YouTube 동영상 경로

스키마 호출을 통해 동영상이 재생될 때 MERCURY_RESULT에서 콜백(MercuryCB)로 'MERCURY_VIDEO_PROMOTION_START = 17' 값이 전달됩니다. 해당 콜백을 받았다면 게임 사운드를 낮추거나 음소거하여 동영상 사운드와 겹치지 않게 조정합니다.
동영상이 종료되면 (닫기 버튼을 누르거나 재생 완료) 'MERCURY_VIDEO_PROMOTION_FINISH = 18' 값이 전달됩니다. 해당 콜백을 받았다면 게임 사운드를 올리거나 복구하여 소리 재생이 가능하도록 합니다. [콜백 타입값 확인하기]
커스텀 보드를 통해 아래 예시처럼 스키마 링크를 설정할 수 있습니다.

동영상 프로모션 사용을 위한 Android 및 iOS 프로젝트 설정
- Android
  - .jar 파일 추가 : YouTubeAndroidPlayerApi.jar
  - 리소스 추가 : [리소스 확인하기]
  - AndroidManifest.xml에 추가
    <activity
    android:name="com.com2us.module.mercury.MercuryVideoActivity"
    android:hardwareAccelerated="true"
    android:screenOrientation="sensorLandscape"
    android:launchMode="standard"/>
    
- iOS
  - WebKit.framework을 추가
동영상 프로모션 설정 시 '플랫폼 서버팀 박충렬 책임, 배하석 선임' 으로 문의바랍니다.

<작성법 참고>

YouTube 동영상 프로모션 기능 강화 (Android & iOS Mercury v2.12.4+)

YouTube에서 제공하는 다양한 옵션을 사용할 수 있도록 기능이 업데이트 되었습니다
- (1-1) Android 설정하기
  - YouTubeAndroidWebPlayerApi.aar 라이브러리를 추가하고 참고해야합니다.
  - AndroidManifest.xml에 아래 내용을 추가합니다.

<작성법 참고>

UserAcquisition 친구 초대 링크 전송 기능 (Android Mercury v2.13.0+, iOS Mercury v2.13.1+)

UserAcquisition 친구 초대 링크 전송 기능을 사용할 수 있도록 업데이트 되었습니다.
- 딥링크 스키마를 받을 수 있도록 설정하기 (Android / iOS)
  - Android Mercury v2.13.0, iOS Mercury v2.13.1 이상 라이브러리를 추가하고 참조해야합니다.
    (Android Mercury v2.12.7, iOS Mercury v2.12.8 버전에 해당 기능이 포함되었으나 해당 버전은 정식 배포된 버전이 아닙니다.)
  - Android ModuleManager v2.5.12 이상 라이브러리를 추가하고 참조해야합니다.
  - [Android] AndroidManifest.xml 및 build.gradle 에 아래 내용을 추가합니다.
    
    <application>
    
    
    <activity ... (생략)...
    <intent-filter >
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="com.com2us.hivesdk.normal.freefull.google.global.android.common" /> 
    
    </intent-filter>
    </activity>
    
    <application/>
    
    <application>
    
    
    <provider
    android:name="com.facebook.FacebookContentProvider"
    android:authorities="com.facebook.app.FacebookContentProvider${facebook_app_id}"
    android:exported="true" />
    
    
    
    <application/>
    // build.gradle에서 facebook의 share 라이브러리를 추가합니다.
    'com.facebook.android:facebook-share:5.4.+'
  - [iOS] 스키마가 전달될 수 있도록 'URL Scheme 추가'을 참고하여 등록합니다. 스키마의 형태는 아래 내용을 참고 바랍니다.
    // 딥링크 터치로 진입 시 액티비티로 들어오는 스키마 형태
    com.com2us.hivesdk.normal.freefull.google.global.android.common://hivePromotionDeepLinkInvite?uatoken=eyJ0eXAiOiJKV1QiLCJhbGciOiJ
초대 링크를 전달하는 입장
- (1) UserAcquisition 초대 링크 및 메시지 정보를 프로모션 서버에 요청
  - UserAcquisition 초대 링크 및 메시지 정보를 반환 받는 API를 호출하여 초대 링크("invite_link")와 초대 메시지("invite_message")를 얻을 수 있습니다.
  - 정보를 반환 받는 API 호출 시 초대 링크를 전달하는 유저의 uid와 프로모션 서버와 사전에 논의된 uatoken 정보를 API의 additionalInfo 파라미터에 넣어 전달합니다. (uatoken 값은 json 포멧으로 전달하며 uatoken 키는 모두 소문자입니다.) (uatoken 값은 초대를 받는 경우 검증에 사용될 수 있으니 게임 서버 등에서 관리 바랍니다.)
    // 반환 데이터 형태
    {"uainfo":{"result_code":"0","result_message":"success","invite_message":"HIVE SDK에 초대합니다. 함께 플레이 하면 즐거움이 두 배 ★☆ 초대문구","invite_link":"http:\/\/test-ua.withhive.com\/ko\/ua684c?t=1571725383"}}
    // result_code 목록
    /**
    0 RESULT_SUCCESS 성공
    100 RESULT_ERROR_SERVER 서버 오류
    200 RESULT_ERROR_PARAMETER 파라메타 전송 오류
    201 RESULT_ERROR_INVALID_PARAMETER 파라메타 유효성 오류
    300 RESULT_ERROR_DATABASE 데이터베이스 오류
    301 RESULT_ERROR_QUERY_FAILED 쿼리 실패
    302 RESULT_ERROR_DATA_NOT_FOUND 조회 실패
    */
- (2) 초대 링크와 초대 메시지를 활용하여 초대 기능 호출
  - 앞서 얻은 초대 링크와 초대 메시지를 활용하여 초대 기능 API를 호출합니다.
  - 초대 기능 API를 호출할 경우 초대 링크와 초대 메시지를 전달할 애플리케이션을 선택하는 UI가 노출됩니다. 애플리케이션을 선택하거나 클립보드에 내용을 복사하는 기능을 사용할 수 있습니다.
초대 링크를 받는 입장
- (1) 초대로 온 링크를 터치합니다.
  - 링크를 터치할 경우 사전에 구성된 웹 페이지가 오픈됩니다. (웹 페이지가 정상 노출되지 않을 경우 GCP 서버팀 프로모션 담당자분께 문의 바랍니다.)
  - 웹 페이지는 '앱 실행', '앱 설치' 버튼을 지원합니다. 앱이 설치되어있지 않을 경우 '앱 설치' 버튼을 눌러 앱이 설치되도록 가이드 부탁드립니다. 앱이 설치되어있을 경우 '앱 실행' 버튼을 눌러 초대 링크에 대한 보상을 받을 수 있습니다.
- (2) '앱 실행'을 통해 앱에 진입한 경우
  - Android/iOS에서 스키마를 받을 수 있는 설정이 정상적으로 되어있다면 아래와 같은 형태의 스키마가 넘어옵니다. 해당 스키마의 'hivePromotionDeepLinkInvite?' 이후 값을 파싱하여 uatoken 값을 받을 수 있습니다.
    // 딥링크 터치로 진입 시 액티비티로 들어오는 스키마 형태
    com.com2us.hivesdk.normal.freefull.google.global.android.common://hivePromotionDeepLinkInvite?uatoken=eyJ0eXAiOiJKV1QiLCJhbGciOiJ
  - Android에서 스키마를 파싱하는 경우 activity에서 intent 데이터를 획득하여 onResume과 onNewIntent 메서드와 아래와 같이 구현할 수 있습니다.
    // Android 예시 코드입니다. 참고 바라며 앱에서 보다 편리한 방법으로 구현하셔도 됩니다.
    @Override
    protected void onResume() {
    super.onResume();
    Intent intent = getIntent();
    Uri data = intent.getData();
    
    if(data != null) {
    Log.d("UATest", "onResume data : " + data.toString());
    
    String[] schemeArr = data.toString().split("'hivePromotionDeepLinkInvite\\?");
    if(schemeArr.length > 1) {
    String[] dataSetArr = schemeArr[1].split("&");
    for(int i = 0; i < dataSetArr.length; i++) {
    String[] keyValueArr = dataSetArr[i].split("=");
    if(keyValueArr.length > 1 && keyValueArr[0].equals("uatoken")) {
    uaToken = keyValueArr[1];
    Log.d("UATest", "onResume receivedUaToken : " + uaToken);
    
    showDialogMsg("[초대받은 유저 UA Token 획득 성공]");
    break;
    }
    }
    }
    }
    
    Log.d("UATest", "onResume intent : " + intent.toString());
    }
    
    @Override
    protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    Bundle intentBundle = intent.getExtras();
    Uri data = intent.getData();
    
    if(data != null) {
    Log.d("UATest", "onNewIntent data : " + data.toString());
    
    String[] schemeArr = data.toString().split("hivePromotionDeepLinkInvite\\?");
    if(schemeArr.length > 1) {
    String[] dataSetArr = schemeArr[1].split("&");
    for(int i = 0; i < dataSetArr.length; i++) {
    String[] keyValueArr = dataSetArr[i].split("=");
    if(keyValueArr.length > 1 && keyValueArr[0].equals("uatoken")) {
    uaToken = keyValueArr[1];
    Log.d("UATest", "onNewIntent receivedUaToken : " + uaToken);
    
    showDialogMsg("[초대받은 유저 UA Token 획득 성공]");
    break;
    }
    }
    }
    }
    
    Log.d("UATest", "onNewIntent intent : " + intent.toString());
    }
  - iOS에서 스키마를 파싱하는 경우 아래와 예시와 같이 구현할 수 있습니다.
    // iOS 예시 코드입니다. 참고 바라며 앱에서 보다 편리한 방법으로 구현하셔도 됩니다.
    
    - (BOOL)application:(UIApplication*)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
    
    NSLog(@"TTTESTTT URL : %@",url);
    
    NSDictionary* dict = [self queryDictionaryFromURL:url];
    
    if(dict!=nil && dict[@"uatoken"]!=nil){
    [[NSUserDefaults standardUserDefaults] setObject:dict[@"uatoken"] forKey:@"mercury_sample_uatoken"];
    [[NSUserDefaults standardUserDefaults] synchronize];
    }
    
    return YES;
    }
    
    - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options
    {
    return [self application:app openURL:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey] annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
    }
    
    - (NSDictionary *)queryDictionaryFromURL:(NSURL *)url
    {
    NSString* query = url.query;
    if (query == nil || query.length == 0)
    return nil;
    
    NSArray* components = [query componentsSeparatedByString:@"&"];
    NSMutableDictionary* dict = [@{} mutableCopy];
    
    for (NSString* component in components) {
    if ([component isEqualToString:@""]) continue;
    
    NSRange range = [component rangeOfString:@"="];
    if (range.location == NSNotFound) {
    [dict setObject:@"" forKey:component];
    }
    else {
    NSString* key = [component substringToIndex:range.location];
    NSString* value = [component substringFromIndex:range.location + range.length];
    [dict setObject:value forKey:key];
    }
    }
    
    return dict;
    }
  - uatoken 값을 게임 서버 등에 관리하고 있는 값인지 확인하여 이상이 없는 경우 초대 링크로 들어온 인원에 보상을 할 수 있습니다.

프로젝트 설정

iOS

유의사항

UIWebView에서 스크롤 동작 오류와 터치가 인식되지 않는 문제
- 참고 : Hub_2.0_적용_가이드_(Unity3d_iOS)#웹뷰 스크롤/터치 인식 문제

프로젝트 설정

Xcode 프로젝트에서 Mercury 모듈 적용 가이드 (iOS)를 따라, 리소스 추가 및 프로젝트 빌트 설정을 수행합니다.
Other Linker Flags에 아래 항목을 추가합니다.
- Debug : -lC2SMercuryUnityPlugin_$(PLATFORM_NAME)d
- Release : -lC2SMercuryUnityPlugin_$(PLATFORM_NAME)

Unity 플러그인 추가

C2SCommonPlugin.unitypackage를 실행하여, CommonPlugin을 추가합니다. (svn://devbackup.com2us.com/Wrapper_redist/program/module/unity/UnityCommonPlugin/)
Mercury Plugin을 추가합니다. (svn://devbackup.com2us.com/Wrapper_redist/program/module/unity/Mercury/Plugin/)
- C2SMercuryPlugin.cs

Mercury 라이브러리를 추가합니다. (svn://devbackup.com2us.com/Wrapper_redist/program/module/unity/Mercury/Plugin/iOS)
- libC2SMercuryUnityPlugin_iphoneosd.a
- libC2SMercuryUnityPlugin_iphoneos.a

Android

기본적인 환경설정 및 API 사용은 Mercury 모듈 적용 가이드 (Android) 와 동일합니다.

Unity Project에 Asset/ Plugins/ Android/ libs 구조로 폴더를 생성하여 아래의 Jar파일들을 추가합니다.
Mercury Plugin : C2SMercuryPlugin.cs 를 추가합니다.

(svn://devbackup.com2us.com/Wrapper_redist/program/module/unity/Mercury/Plugin/)

<작성법 참고>

Jar 파일 추가 (Java Libraries)

Add JARS...

MercuryUnityPlugin.jar	(svn://devbackup.com2us.com/Wrapper_redist/program/module/unity/Mercury/Plugin)
mercury.jar	(svn://devbackup.com2us.com/Wrapper_redist/program/templates/AndroidTemplate/Com2uSAndroid/module/Mercury/libs/)
modulemanager.jar	(svn://devbackup.com2us.com/Wrapper_redist/program/templates/AndroidTemplate/Com2uSAndroid/module/ModuleManager/libs/)
	Mercury 2.5.3 버전 에서 mercury main page내 offerwall 호출 기능이 추가 되었기 때문에, Mercury 2.5.3 이상을 적용 하실 경우 Offerwall.jar도 추가 해 주셔야 합니다.
offerwall.jar	(svn://devbackup.com2us.com/Wrapper_redist/program/templates/AndroidTemplate/Com2uSAndroid/module/Offerwall/libs/)