Mercury 모듈 레퍼런스 가이드

상수 및 자료형

MERCURY_RESULT

* Mercury open/close result

typedef enum _MERCURY_RESULT
{
// Mercury full banner & main page
MERCURY_OPEN = 1, // 모듈 Full Banner 웹뷰 열림 알림
MERCURY_CLOSE = 2, // 모듈 Full Banner 웹뷰 닫힘 알림
MERCURY_FORCED_OPEN = 3, // 모듈 Main Page 웹뷰 열림 알림
MERCURY_FORCED_CLOSE = 4, // 모듈 Main Page 웹뷰 닫힘 알림
MERCURY_NOTICE_OPEN = 5, // 모듈 Notice Only 웹뷰 열림 알림
MERCURY_NOTICE_CLOSE = 6, // 모듈 Notice Only 웹뷰 닫힘 알림

// Custom board & view
MERCURY_CUSTOM_OPEN = 7, // 모듈 Custom board 뷰 열림 알림
MERCURY_CUSTOM_CLOSE = 8, // 모듈 Custom board 뷰 닫힘 알림

MERCURY_CUSTOM_BOARD_OPEN = MERCURY_CUSTOM_OPEN,
MERCURY_CUSTOM_BOARD_CLOSE = MERCURY_CUSTOM_CLOSE,
MERCURY_CUSTOM_VIEW_OPEN = 9, // 모듈 Custom 웹뷰 열림 알림
MERCURY_CUSTOM_VIEW_CLOSE = 10, // 모듈 Custom 웹뷰 닫힘 알림

// Review popup
MERCURY_REVIEW_OPEN = 11, // 리뷰 팝업 열림 알림
MERCURY_REVIEW_CLOSE = 12, // 리뷰 팝업 닫힘 알림

// Moregames popup (Android Only)
MERCURY_MOREGAMES_OPEN = 13, // 모어게임즈 팝업 열림 알림
MERCURY_MOREGAMES_CLOSE = 14, // 모어게임즈 팝업 닫힘 알림
MERCURY_MOREGAMES_CLOSE_WITH_APP_TERMINATION = 15, // 모어게임즈 팝업 닫힘 & 사용자가 앱 종료하기 선택함 알림

// Network error
MERCURY_NETWORK_DISCONNECT = 16 // 네트워크 접속장애 알림

// YouTube Video Promotion
MERCURY_START_PLAYBACK = 17 // 동영상 재생 시작을 알림
MERCURY_FINISH_PLAYBACK = 18 // 동영상 재생 종료를 알림

// 스키마를 통한 창 닫는 기능 - added Android Mercury 2.13.2, iOS Mercury 2.13.3
MERCURY_MAIN_GOBACK = 19, // 프로모션 페이지 뒤로 가기 닫힘 (Main Page)
MERCURY_NOTICE_GOBACK = 20, // 프로모션 페이지 뒤로 가기 닫힘 (Notice)
MERCURY_CUSTOM_BOARD_GOBACK = 21, // 프로모션 페이지 뒤로 가기 닫힘 (Board)
MERCURY_CUSTOM_VIEW_GOBACK = 22 // 프로모션 페이지 뒤로 가기 닫힘 (CustomView)

} MERCURY_RESULT;

MERCURY_CUSTOM_RESULT

* Get CustomViewInfo result

typedef enum _MERCURY_CUSTOM_RESULT
{
MERCURY_SUCCESS = 0,
MERCURY_FAILED = -1
MERCURY_INVALID_PARAM = -2 // added Android Mercury 2.12.7, iOS Mercury 2.12.8

} MERCURY_CUSTOM_RESULT;

MERCURY_SHOW_TYPE

* Mercury Show type

typedef enum _MERCURY_SHOW_TYPE
{
// Mercury full banner
MERCURY_SHOW_EVENT_LEGACY = -9, // Full Banner(Webview) (Android Mercury v2.14.0+, iOS Mercury v2.14.0+)
MERCURY_SHOW_EVENT = -11, // Full Banner

// Mercury main page
MERCURY_SHOW_NOTICE_TOP = -12, // Main Page (공지사항 위쪽 배치)
MERCURY_SHOW_NOTICE_BOTTOM = -13, // Main Page (공지사항 아래쪽 배치)
MERCURY_SHOW_FORCED_NOTICE_TOP = -14, // Main Page (공지사항 위쪽 배치 + 하루안보기 무시)
MERCURY_SHOW_FORCED_NOTICE_BOTTOM = -15, // Main Page (공지사항 아래쪽 배치 + 하루안보기 무시)

// Mercury notice
MERCURY_SHOW_NOTICE_ONLY = -16, // Notice Only (공지사항만 표시)
MERCURY_SHOW_FORCED_NOTICE_ONLY = -17, // Notice Only (공지사항만 표시 + 하루안보기 무시)

// Custom show type
// Base <= type < MAX
MERCURY_SHOW_CUSTOM_BASE = 100000, // Custom board
MERCURY_SHOW_CUSTOM_BOARD_BASE = MERCURY_SHOW_CUSTOM_BASE,
MERCURY_SHOW_CUSTOM_BOARD_MAX = MERCURY_SHOW_CUSTOM_BASE + 200000,

MERCURY_SHOW_CUSTOM_VIEW_BASE = MERCURY_SHOW_CUSTOM_BOARD_MAX,
MERCURY_SHOW_CUSTOM_VIEW_MAX = MERCURY_SHOW_CUSTOM_VIEW_BASE + 200000
} MERCURY_SHOW_TYPE;

MERCURY_BADGE_TARGET

* Badge request & response code

typedef enum _MERCURY_BADGE_TARGET
{
MERCURY_BADGE_FOR_EVENT = -20, // Badge for 'Full banner'
MERCURY_BADGE_FOR_NOTICE = -21, // Badge for 'Main page'
MERCURY_BADGE_FOR_NOTICE_ONLY = -22, // Badge for 'Notice Only'
MERCURY_BADGE_FOR_NONE = -23, // Badge not found

// Custom board & view
// Base <= target < MAX
MERCURY_BADGE_FOR_CUSTOM_BASE = 100000,
MERCURY_BADGE_FOR_CUSTOM = MERCURY_BADGE_FOR_CUSTOM_BASE,
MERCURY_BADGE_FOR_CUSTOM_MAX = MERCURY_BADGE_FOR_CUSTOM_BASE + 200000,

MERCURY_BADGE_FOR_CUSTOM_BOARD_BASE = MERCURY_BADGE_FOR_CUSTOM_BASE,
MERCURY_BADGE_FOR_CUSTOM_BOARD_MAX = MERCURY_BADGE_FOR_CUSTOM_MAX,

MERCURY_BADGE_FOR_CUSTOM_VIEW_BASE = MERCURY_BADGE_FOR_CUSTOM_BOARD_MAX,
MERCURY_BADGE_FOR_CUSTOM_VIEW_MAX = MERCURY_BADGE_FOR_CUSTOM_VIEW_BASE + 200000

} MERCURY_BADGE_TARGET;

MERCURY_BADGE_TARGET

* Badge type

typedef enum _MERCURY_BADGE_TYPE
{
MERCURY_BADGE_TYPE_NONE = -24,
MERCURY_BADGE_TYPE_NEW = -25,
MERCURY_BADGE_TYPE_MAX = -26

} MERCURY_BADGE_TYPE;

Mercury (Java source / C# source only)

* Java source / C# source only

public class Mercury
{
// Mercury Badge Type
public static final int MERCURY_BADGE_TYPE_NEW = -20;
public static final int MERCURY_BADGE_TYPE_MAX = -21;

// Mercury Callback for Default Action
public static final int MERCURY_FULL_BANNER_OPENED = -6;
public static final int MERCURY_FULL_BANNER_CLOSED = -7;
public static final int MERCURY_MAIN_PAGE_OPENED = -8;
public static final int MERCURY_MAIN_PAGE_CLOSED = -9;
public static final int MERCURY_NOTICE_ONLY_OPENED = -10;
public static final int MERCURY_NOTICE_ONLY_CLOSED = -11;
public static final int MERCURY_CUSTOM_OPENED = -12;
public static final int MERCURY_CUSTOM_CLOSED = -13;
public static final int MERCURY_NETWORK_DISCONNECTED = -14;

// Mercury Badge For What
public static final int MERCURY_BADGE_FOR_ALL = 0;
public static final int MERCURY_BADGE_FOR_FULL_BANNER = -15;
public static final int MERCURY_BADGE_FOR_MAIN_PAGE = -16;
public static final int MERCURY_BADGE_FOR_NOTICE_ONLY = -17;
public static final int MERCURY_BADGE_FOR_CUSTOM_BASE = 100000;
public static final int MERCURY_BADGE_FOR_CUSTOM_NEW = MERCURY_BADGE_FOR_CUSTOM_BASE;
public static final int MERCURY_BADGE_FOR_CUSTOM_MAX = MERCURY_BADGE_FOR_CUSTOM_BASE+200000;

// Mercury Show Type
public static final int MERCURY_GET_BADGE_LIST = -10;
public static final int MERCURY_SHOW_EVENT = -11;
public static final int MERCURY_SHOW_NOTICE_TOP = -12;
public static final int MERCURY_SHOW_NOTICE_BOTTOM = -13;
public static final int MERCURY_SHOW_FORCED_NOTICE_TOP = -14;
public static final int MERCURY_SHOW_FORCED_NOTICE_BOTTOM = -15;
public static final int MERCURY_SHOW_NOTICE_ONLY = -16;
public static final int MERCURY_SHOW_FORCED_NOTICE_ONLY = -17;
public static final int MERCURY_SHOW_CUSTOM_BASE = 100000;
public static final int MERCURY_SHOW_FORCED_CUSTOM_BASE = 200000;
}

MERCURY_SHOW_NOTICE_TOP, BOTTOM 에 따라 <공지사항 및 안내사항> , <Events> 의 위치를 바꿀 수 있습니다.

함수

void CS_MercurySetCallBack(MercuryCB callback)

Description
Mercury의 콜백을 받는 함수를 등록합니다.
Return Value

void

Parameter

in/out	Type	Name	Description
in	MercuryCB	callback	Callback을 받는 함수입니다.

Remark
Android 에서는 setCallBack(MercuryCB callback) 과 동일

void CS_MercuryShowEx(const char* uid, MERCURY_SHOW_TYPE mercuryShowType, const char* additionalInfo)

Description
Event, Notice_Top /Bottom, Forced_Notice_Top/ Bottom을 하나로 호출할 수 있게 만든 함수입니다.
TypeEnum값을 통해 어떤 방식으로 보여줄 지 결정합니다.
additionalInfo 인자를 통해 Mercury Server로 추가 정보를 전달할 수 있습니다.
additionalInfo에 mq_redirect 값을 적용하여 호출하면 백오피스에 등록된 머큐리 이벤트 페이지가 머큐리 메인페이지를 출력하지 않고 바로 이벤트 해당 페이지가 출력됩니다.

기존 함수와 대응되는 형태는 아래와 같습니다.
CS_MercuryShowForEvent -> CS_MercuryShowEx( MERCURY_SHOW_EVENT )
CS_MercuryShowForNotice -> CS_MercuryShowEx( MERCURY_SHOW_EVENT )
CS_MercuryForcedShowForEvent -> CS_MercuryShowEx( MERCURY_SHOW_FORCED_NOTICE_BOTTOM )
CS_MercuryForcedShowForNotice -> CS_MercuryShowEx( MERCURY_SHOW_FORCED_NOTICE_TOP )

Return Value

void

Parameter

in/out	Type	Name	Description
in	const char*	uid	uid를 설정합니다. (CS_MercurySetUid에서 설정한 값과 동일합니다.)
in	MERCURY_SHOW_TYPE	mercuryShowType	Show Type을 설정합니다. (상단의 Type enum값 참고)
in	const char*	additionalInfo	server로 전달 할 추가 정보를 Json형식으로 넘깁니다. 사용하지 않을 시, ""을 넘깁니다. ex> "{"AMS":"game-server1:character-name01"}", "{"AMS":"game-server1:character-name01" ,"GMS":"game-server1" }" mq_redirect를 사용하면 머큐리 백오피스에서 등록한 (이벤트 번호를 부여받은) 특정 이벤트 페이지의 URL을 바로 출력 할 수 있다. additionalInfo에 "mq_redirect" : "이벤트 번호"를 적용하여 호출하면 백오피스에 등록된 머큐리 이벤트 페이지가 머큐리 메인페이지를 출력하지 않고 바로 해당 이벤트 페이지가 출력된다. ex> addtionalInfo : "{"server":"서버 지역 코드값","character":"0", "mq_redirect":"이벤트번호"}" mq_redirect로 호출할 때, 2016/07/04일 이후 등록된 이벤트에 한해 "header":"off"를 추가하면 이벤트 페이지 상단의 헤더가 나타나지 않는다. ex> addtionalInfo : "{"server":"서버 지역 코드값","character":"0", "mq_redirect":"이벤트번호", "header":"off"}"

Remark
Android 에서는 mercuryShowEx() 와 동일

int CS_MercuryGetCustomViewInfo(const char* uid, int viewID, MercuryCBWIthData customViewCallback)

Description
공지사항, 이벤트, Custom View의 정보를 Json 형태의 스트링으로 Callback을 통하여 전달해 주는 함수입니다.
Callback을 지정하고, 원하는 ShowType을 입력하면 됩니다.
또한, 뷰의 badge 정보도 포함하고 있습니다. 머큐리에서 제공하는 웹뷰를 사용하지 않을 때, 이 함수를 통해 받은 정보로 웹뷰 내의 컨텐츠를 채울 수 있습니다.
Return Value

MERCURY_CUSTOM_RESULT (SUCCESS, FAILED)

Parameter

in/out	Type	Name	Description
in	const char*	uid	uid를 설정합니다. (CS_MercurySetUid에서 설정한 값과 동일합니다.)
in	int	viewID	Custom Info를 요청 할 viewID(ShowType)입니다.
in	MercuryCBWIthData	customViewCallback	결과 Data를 전달 받을 Callback을 지정합니다.

Remark
Android Wrapper를 이용하는 경우, callback으로 받은 char *jsonData를 Copy해서 사용해야 합니다.
Mercury 내부에서 jsonData를 넘기고 release합니다.

API 호출 시 Badge정보가 순차적으로 MercuryCB Callback을 통해 전달된 후, 최종적으로 MercuryCBWithData Callback으로 MERCURY_CUSTOM_RESULT, jsonData가 전달됩니다.
따라서, Badge 정보와 MERCURY_CUSTOM_RESULT는 서로 다른 콜백에서 처리해야 합니다.

int CS_MercuryShowReviewPopup(const char* uid, const char* vid, const char* did)

Description
사용자에게 앱 리뷰를 유도하는 팝업을 노출합니다.
팝업 노출 시 MERCURY_RESULT 콜백이 호출됩니다. Result code는 MERCURY_REVIEW_OPEN입니다.
팝업 노출 여부는 서버에서 판단하며, 사용자의 응답이 서버에 기록됩니다.
Return Value

0 : Request success.
-1 : Request fail.

Parameter

in/out	Type	Name	Description
in	const char*	uid	UID 입니다.
in	const char*	vid	VID 입니다.
in	const char*	did	DID 입니다.

Remark
팝업 노출 후 사용자의 액션에 따른 동작.
기본적으로 MERCURY_RESULT 콜백이 호출되며, Result code는 MERCURY_REVIEW_CLOSE입니다.
1. 다음에 하기 (Later) : 팝업이 닫히며, API 호출 시 팝업이 다시 노출됩니다.
2. 하지 않기 (No thanks) : 팝업이 닫히며, 게임 버전이 바뀌기 전까지 팝업이 노출되지 않습니다.
3. 하러 가기 (Go) : 팝업이 닫히며, 앱 스토어로 Redirect 됩니다. 이후, 게임 버전이 바뀌기 전까지 팝업이 노출되지 않습니다.

int CS_MercuryShowNativeReviewPopup(const char* uid, const char* vid, const char* did)

Description
iOS의 경우, 게임 내에서 즉시 별점과 리뷰를 남길 수 있습니다. 기존의 리뷰 팝업과는 달리, 마켓으로 이동 없이 게임 내에서 즉시 별점 제출이 가능하며 리뷰를 요청할 경우 작성 페이지로 즉시 이동이 가능 합니다.
팝업 노출 시 콜백이 호출되지 않습니다.

iOS 인게임 리뷰 팝업에 대해 HIVE 가 권장하는 정책은 다음과 같습니다.
- HIVE에서 제공하는 게임 리뷰 팝업을 그대로 사용하는 경우, ios 인게임 리뷰 팝업과 동시 사용 가능
- 단, 게임별로 커스텀한 리뷰 팝업을 사용하는 경우, ios 인게임 리뷰 팝업과 동시 사용 불가
- Mercury 2.12.0 이상에서 동작

또한 ios 인게임 리뷰 팝업은 애플의 정책에 따라 노출됩니다.
- 노출 순서 및 텍스트, UI 등 커스텀 불가
- 각 앱 당 디바이스 별로 연 3회 까지만 노출 되며, 팝업 노출 여부는 Apple 내부 정책에 의해 동작하므로 수동으로 변경 불가능
- iOS 10.3 버전 이상에서만 동작
- 유저가 기기 설정에서 '앱 내 평가 및 리뷰' 항목을 OFF처리 한 경우 노출되지 않음
- 단, 개발중인 빌드에서는 노출 횟수와 관계 없이 항상 노출되며, 마켓에 평점을 제출 할 수 없습니다.
Return Value

0 : Request success.
-1 : Request fail.

Parameter

in/out	Type	Name	Description
in	const char*	uid	UID 입니다.
in	const char*	vid	VID 입니다.
in	const char*	did	DID 입니다.

Remark
iOS 인게임 리뷰 팝업 미지원 OS 및 안드로이드 디바이스에서 해당 API를 호출하는 경우, 기존 HIVE SDK에서 제공하는 Review 팝업이 노출되며, 해당 팝업이 동작은 기존 리뷰 팝업에서의 노출 조건과 동일하나 콜백이 존재하지 않습니다.

int CS_MercuryShowMoregamesPopup(const char* uid, const char* vid, const char* did)

Description
유저가 Back버튼을 누르면 노출되는 게임 종료 팝업입니다. (메인화면과 같은 화면에서 Back키로 게임을 종료하는 시점)
하이브 연동 게임을 추천하는 기능이 포함되어있습니다.
Return Value

MERCURY_CUSTOM_RESULT (SUCCESS, FAILED)

Parameter

in/out	Type	Name	Description
in	const char*	uid	UID 입니다.
in	const char*	vid	VID 입니다.
in	const char*	did	DID 입니다.

Remark
Android 전용 API 입니다.

void CS_MercurySetUid(const char* uid)

Description
뉴스배너를 위한 UID 값을 세팅합니다. 항상 로그인 완료 콜백 후에 함수 호출합니다.
Return Value

void

Parameter

in/out	Type	Name	Description
in	const char*	uid	UID.

Remark
Android 에서는 setUid(String uid)와 동일

void CS_MercurySetIsUsingStaging(int isUsingStaging)

Description
테스트 서버 사용 여부를 설정합니다. 기본옵션은 false입니다.
Return Value

void

Parameter

in/out	Type	Name	Description
in	int	isUsingStaging	테스트 서버 사용 여부를 설정합니다. 기본옵션은 false입니다. true : 테스트 서버로 접속 false : 상용 서버로 접속

Remark
Android 에서는 setIsUsingStaging(boolean isUsingStaging) 와 동일

void CS_MercurySetLog(int isLog)

Description
0 - log off, 1 - log on
Return Value

void

Parameter

in/out	Type	Name	Description
in	int	isLog	Android Log 설정. 기본 false. iOS에서는 debug library 사용.

Remark
Android 에서는 setLogged(boolean b) 와 동일

const char* CS_MercuryGetVersion()

Description
[iOS 전용] Mercury 버전을 가져옵니다.
Return Value

version

Remark
Android 에서는 getVersion 사용.

void CS_MercuryGetBadge(const int badgeTarget)

Description
badgeTarget에 해당하는 웹뷰(Main Page, Full Banner 등)에 Badge를 표시해야 할 지의 여부를 조회함. Badge를 표시해야 하는 경우, _MERCURY_BADGE_TARGET에 정의된 값이 콜백으로 옴. 요청 시 파라미터로 넘긴 값과 콜백으로 오는 값이 동일해야 정상.
Return Value

void

Parameter

in/out	Type	Name	Description
in	const int	badgeTarget	badgeTarget으로는 _MERCURY_BADGE_TARGET에 해당하는 값을 넘긴다.

Remark
Android 에서는 mercuryGetBadge 사용.

int CS_MercuryGetBadgeType(const int badgeTarget)

Description
badgeTarget에 해당하는 웹뷰에 붙을 badge가 어떤 타입인지 리턴함. badge의 타입은 _MERCURY_BADGE_TYPE에 정의되어 있음.
Return Value

Badge Type Enum

Parameter

in/out	Type	Name	Description
in	const int	badgeTarget	badgeTarget으로는 _MERCURY_BADGE_TARGET에 해당하는 값을 넘긴다.

Remark
Android 에서는 mercuryGetBadgeType 사용.

int CS_MercuryRequestUAInfo(const char* uid, const char* additionalInfo, MercuryCBWithData callbackWithData)

Description
UserAcquisition 친구 초대 링크 및 메시지 데이터를 프로모션 서버로부터 반환받는 API (Android Mercury v2.12.7, iOS Mercury v2.12.8 이상)
Return Value

MERCURY_SUCCESS

Parameter

in/out	Type	Name	Description
in	const char*	uid	로그인된 유저의 uid(게스트 uid 혹은 HIVE 정식 유저 uid) & 초대 링크를 전달할 유저의 uid
in	const char*	additionalInfo	uatoken 데이터를 json 포맷으로 구성해 additionalInfo 파라미터에 전달합니다. ex) String additionalInfo = "{\"uatoken\":\"asdf1234qwer5678\"}";
in	MercuryCBWithData	callbackWithData	UserAcquisition 친구 초대 링크 및 메시지 데이터를 전달받을 데이터 콜백 ex) "{ "uainfo":{"result_code":"0","result_message":"success","invite_message":"HIVE SDK에 초대합니다. 함께 플레이 하면 즐거움이 두 배!","invite_link":"http:\/\/test-ua.withhive.com\/ko\/ua685c?t=1571650561"} }"

Remark
Android 에서는 mercuryRequestUAInfo 사용.

int CS_MercuryRequestUALinkShare(const char* urlLink, const char* shareMessage)

Description
UserAcquisition 친구 초대 링크 및 메시지를 특정 외부 애플리케이션에 전달하는 API, 외부 애플리케이션을 외에 링크와 메시지를 클립보드에 복사하는 기능도 제공 (Android Mercury v2.12.7, iOS Mercury v2.12.8 이상)
Return Value

MERCURY_SUCCESS

Parameter

in/out	Type	Name	Description
in	const char*	urlLink	초대 받을 유저가 터치하여 사용할 수 있는 초대 딥링크 url CS_MercuryRequestUAInfo 호출로 응답받은 'invite_link' 값을 해당 파라미터에 넣어 사용할 수 있습니다.
in	const char*	shareMessage	초대 링크와 같이 전달될 메시지 입니다. CS_MercuryRequestUAInfo 호출로 응답받은 'invite_message' 값을 해당 파라미터에 넣어 사용할 수 있습니다.

Remark
Android 에서는 mercuryRequestUALinkShare 사용.

int CS_MercuryGetBannerInfo(const char* campaignType, const char* bannerType, MercuryCBWithData bannerInfoCallback)

Description
- 게임에서 배너를 원하는 규격으로 자유롭게 노출할 수 있도록 지원한다. (Android Mercury v2.13.3, iOS Mercury v2.13.4 이상)

HIVE에서 제공하는 API가 배너 데이터를 가져오면, 게임에서는 제공받은 데이터를 활용하여 특정 위치에 배너를 표시할 수 있다.
데이터를 정상적으로 전달받았다면 API를 적용한 배너 클릭 시 전달받은 pid값을 CS_MercuryShowEx 메서드의 additionalInfo에 mq_redirect 값으로 전달하여 노출할 수도 있다.

Return Value

MERCURY_SUCCESS

Parameter

in/out	Type	Name	Description
in	const char*	campaignType	great : 대배너 small : 일반 배너 rolling : 롤링 배너
in	const char*	bannerType	all : 모든 타입 event : 이벤트 타입 notice : 공지 타입
in	MercuryCBWithData	bannerInfoCallback	배너 정보 데이터를 전달받을 데이터 콜백 ex)"{"bannerinfo":[{"type_banner":"great","start_date":"2019-07-16 11:47:00","image":"https:\/\/image-glb.qpyou.cn\/\/hivepromotion\/banner\/1907\/4733_1563245291_ja.gif","link":"http:\/\/promotion.qpyou.cn\/news\/direct\/236275","end_date":"2029-08-03 11:47:00","type_link":"webview","pid":"236275"}]}

Remark
Android 에서는 getBannerInfo 사용.

java / C# only

Mercury(Activity activity)

Description
Android 생성자.
Return Value

no return value

Parameter

in/out	Type	Name	Description
in	Activity	activity	Activity

Remark
Android 에서 jni를 사용하지 않을 경우에 사용함.

String getVersion()

Description
Android 에서 사용. Module version을 리턴함.
Return Value

version

Remark
Android 에서 jni를 사용하지 않을 경우에 사용함.

void CS_MercuryInitImageLoader()

Description
이미지 타입 전면 배너에 필요한 정보를 초기화 및 사전 다운로드 합니다.
[Case 1 : 해당 API 호출하였다면]CS_MercuryShowEx로 MERCURY_SHOW_EVENT 타입 호출 시 이미지 타입 전면 배너가 노출됩니다. 만약 해당 API 호출 이후 웹뷰 타입의 전면 배너를 호출하고 싶다면 MERCURY_SHOW_EVENT_LEGACY 타입으로 호출 가능합니다.
[Case 2 : 해당 API 호출하지 않았다면]CS_MercuryShowEx로 MERCURY_SHOW_EVENT 타입 호출 시 웹뷰 타입 전면 배너가 노출됩니다.
(Android Mercury v2.14.0+, iOS Mercury v2.14.0+)
Return Value

void

Parameter

no parameter

Remark
Android Java : initImageLoader(), C# : mercuryInitImageLoader()

콜백 함수

typedef void (*MercuryCB)(MERCURY_RESULT result)

Description
iOS / Wrapper에서의 콜백함수 타입을 정의합니다.
Return Value

typedef void

Parameter

in/out	Type	Name	Description
in	MERCURY_RESULT	result	callback

Remark
not comment
Sample Code

// iOS / Wrapper mercury callback 함수 예시
void mercuryCB(MERCURY_RESULT result)
{
switch(result)
{
case MERCURY_OPEN:
NSLog(@"MERCURY_OPEN");
break;
case MERCURY_CLOSE:
NSLog(@"MERCURY_CLOSE");
break;
case MERCURY_FORCED_OPEN:
NSLog(@"MERCURY_FORCED_OPEN");
break;
case MERCURY_FORCED_CLOSE:
NSLog(@"MERCURY_FORCED_CLOSE");
break;
case MERCURY_NETWORK_DISCONNECT:
NSLog(@"MERCURY_NETWORK_DISCONNECT");
break;
case MERCURY_START_PLAYBACK:
NSLog(@"MERCURY_START_PLAYBACK");
// set game sound volume off
break;
case MERCURY_FINISH_PLAYBACK:
NSLog(@"MERCURY_FINISH_PLAYBACK");
// set game sound volume on
break;
default:
break;

}
}

typedef void (MercuryCBWithData)(MERCURY_RESULT result, const char additionalInfo)

Description
iOS / Wrapper에서 Data가 포함 된 콜백 함수를 정의합니다.
Return Value

typedef void

Parameter

in/out	Type	Name	Description
in	MERCURY_RESULT	result	callback
in	const char*	additionalInfo	json string

Remark
not comment
Sample Code

// iOS / Wrapper mercury callback with Data 함수 예시
void mercuryCBWithData(MERCURY_RESULT result, const char* jsonData)
{
NSLog(@"Mercury callback with data : %s", jsonData);

switch(result)
{
case MERCURY_SUCCESS:
{
if(jsonData == NULL) return;

// CString 파싱
NSString *convertStr = [NSString stringWithUTF8String:jsonData];
NSError *error = nil;
NSDictionary *dataDict = [NSJSONSerialization JSONObjectWithData:[convertStr dataUsingEncoding:NSUTF8StringEncoding]
options:NSJSONReadingAllowFragments error:&error];

if(error)
{
NSLog(@"%@", [error localizedDescription]);
return;
}

NSLog(@"Parsed dictionary = %@", dataDict);

// customViewInfo 콜백
NSDictionary *customViewInfo = [dataDict objectForKey:@"customviewinfo"];

if(customViewInfo)
{
// 뱃지 정보
// badgetype = new;
// expire = 24; (min)
// showtype = 200001;
// startdate = 1434070800; (sec : interval since1970)
// term = 30; (min)
NSDictionary *badgeInfo = [customViewInfo objectForKey:@"badge"];

NSLog(@"Badge info : %@", badgeInfo);

// URL 정보 얻어오기
NSString *urlStr = [customViewInfo objectForKey:@"url"];
NSURL *url = [NSURL URLWithString:urlStr];

NSLog(@"URL info : %@", url.absoluteString);

// Cookies 정보 얻어오기
// (iOS Mercury v2.12.7 이상( Android Mercury v2.12.6 이상))
// (해당 버전부터는 각 OS가 제공하는 Cookie를 사용하지 않기 때문에 Cookie에서 취급되었던 데이터를 post 데이터로 전송해야 한다. 때문에 Cookies에 있는 값을 얻은 후 Mercury 뷰 호출 시 꼭 post 데이터로 넣어서 요청해야 한다.)
NSDictionary *cookiesDict = [customViewInfo objectForKey:@"cookies"];

NSLog(@"cookies info : %@", cookiesDict);

// Test Webview Loading
WebviewTestViewController *webViewController = [[WebviewTestViewController alloc] initWithNibName:@"WebviewTestViewController" bundle:[NSBundle mainBundle]];

[viewControllerSharedInstance presentViewController:webViewController animated:YES completion:^{
NSURL *webURL = [NSURL URLWithString:@"http://test.mercury.com2us.com/test/printCookie"];
NSURLRequest *request = [NSURLRequest requestWithURL:webURL];

webViewController.customURL = url;
webViewController.cookiesDict = cookiesDict;
[webViewController.webView loadRequest:request];
}];
}

// uainfo 콜백
NSDictionary *uainfo = [dataDict objectForKey:@"uainfo"];

if(uainfo)
{
// 초대 정보
// invite_link = https://ua.withhive.com/ko/ua1585188c?t=1569567736;
// invite_message = 최초 접속 시, 무조건 5성 소환권 지급!
// result_code = 0
// result_message = success

NSString* urlLink = uainfo[@"invite_link"];
NSString* message = uainfo[@"invite_message"];

CS_MercuryRequestUALinkShare([urlLink UTF8String], [message UTF8String]);
}

}
break;

case MERCURY_FAILED:

break;

default:
break;

}
}

// iOS / Wrapper mercury callback with Data webview post 예시
- (IBAction)openCustomURL:(id)sender
{
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:self.customURL];

// cookie 값 post 데이터에 추가
NSError* error = nil;
NSMutableDictionary* jsonData = [[NSMutableDictionary alloc]init];
[jsonData setObject:self.cookiesDict forKey:@"cookies"];

NSLog(@"webView jsonBody : %@", jsonData);
NSData *dataJSon = [NSJSONSerialization dataWithJSONObject:jsonData options:0 error:&error];

// Make url request.
[request setHTTPBody:dataJSon];
[request setHTTPMethod:@"POST"];

[self.webView loadRequest:request];
}

/**
* Android Mercury 모듈의 mercuryGetCustomViewInfo API를 호출하여 커스텀뷰 관련 정보 및 cookies 정보를 받는 예
* (Java 코드로 작성되었습니다.)
*/

Mercury libMercury; // Mercury 클래스 객체
JSONObject cookiesJson; // 쿠키 데이터를 임시 관리할 객체
String uid = “123456789”;
int viewId = 0;

//… Mercury 모듈 초기화 등의 로직은 생략 …

// [1]
// FnMercuryCBWithData 라는 예제 클래스를 구현한 예
// (FnMercuryCBWithData 클래스는 MercuryCBWithData 콜백을 처리하는 역할을 합니다.)
private static class FnMercuryCBWithData implements MercuryCBWithData
{
@Override
public void mercuryCallBackWithData(int result, String jsonData) {
// TODO Auto-generated method stub
if(result == Mercury.MERCURY_SUCCESS)
{
try
{
JSONObject jsonObj = new JSONObject(jsonData);

// TODO : jsonData에서 게임앱에서 필요한 데이터를 수집합니다.
// 그리고 Android Mercury v2.12.6 이상부터는 “cookies” 키 데이터가 추가로 전달되고,
// 해당 키 값을 머큐리의 커스텀 뷰 자체 구현 노출 시 포함시켜 호출합니다.

JSONObject jsonCustomViewInfo = jsonObj.getJSONObject(“customviewinfo”);
cookiesJson = jsonCustomViewInfo.getJSONObject(“cookies”); // 쿠키 데이터를 객체에 보관

}
catch(JSONException e)
{
e.printStackTrace();
}
}
}
}

// [2]
// getMercuryCustomViewInfo 라는 예제 메서드를 구현한 예
// (getMercuryCustomViewInfo 메서드는 커스텀뷰 정보 API를 호출하는 역할을 합니다.)
public void getMercuryCustomViewInfo()
{
// mercuryGetCustomViewInfo API 호출
libMercury.mercuryGetCustomViewInfo(uid, viewId, new FnMercuryCBWithData());
}

// [3]
// 커스텀 뷰 정보 응답 결과 예
// (위 Java 코드의 public void mercuryCallBackWithData(int result, String jsonData) 에서 jsonData의 예)
/*
{"customviewinfo":{"origin":{"error":0,"errormsg":"Success.","count":5,"show":"1","type":"0","webview":[{"pid":"238803","webview_type":"fullbanner","board":"custom","url":"https:\/\/m-mercury.qpyou.cn\/news\/v1_banner","image_url":"","down_url":"","action":"none","margin":0,"wratio":9,"hratio":16,"cpi_type":0,"act":"init","showtype":"-11"},{"pid":"236272","webview_type":"fullbanner","board":"custom","url":"https:\/\/m-mercury.qpyou.cn\/news\/v1_banner","image_url":"","down_url":"","action":"none","margin":0,"wratio":9,"hratio":16,"cpi_type":0,"act":"init","showtype":"-11"},{"pid":"236275","webview_type":"fullbanner","board":"custom","url":"https:\/\/m-mercury.qpyou.cn\/news\/v1_banner","image_url":"","down_url":"","action":"none","margin":0,"wratio":9,"hratio":16,"cpi_type":0,"act":"init","showtype":"-11"},{"pid":"236274","webview_type":"fullbanner","board":"custom","url":"https:\/\/m-mercury.qpyou.cn\/news\/v1_banner","image_url":"","down_url":"","action":"none","margin":0,"wratio":9,"hratio":16,"cpi_type":0,"act":"init","showtype":"-11"},{"pid":"236271","webview_type":"fullbanner","board":"custom","url":"https:\/\/m-mercury.qpyou.cn\/news\/v1_banner","image_url":"","down_url":"","action":"none","margin":0,"wratio":9,"hratio":16,"cpi_type":0,"act":"init","showtype":"-11"}],"badge":[],"use_cutout":true},"url":"https:\/\/m-mercury.qpyou.cn\/news\/v1_banner","cookies":{"peppermint_version":"Hive v.2.7.11","appid":"com.com2us.hivesdk.normal.freefull.google.global.android.common","device":"SM-N920K","platform":"android","os_version":"7.0","hub_ck2":"88e865a0e736f7c4869341c01c7d0cb64ba191dd08237b999629952580dba425tvMgqodTWou3Tg8mLpa\/iQ==","hub_ck3":"6b377893cde771696e2e62a903c4fa42a8379b748c8c810536199558c6b75f38pBe+3\/LDhtYwzkLeut61SjpvcWo\/2vZNyM\/C\/SBvSWU=","did":"541821123","enable_cookie":"no","language":"ko","device_country":"kr","device_model":"SM-N920K","promotion_version":"2.12.7","app_version":"1.18.0","app_version_code":"60","orient":"1","top_type":"event","vid":"129442100","additionalInfo":"","mcc":"450","mnc":"08","forced":"off","advertising_id":"8003f869-36fa-48e6-99f9-fcb5025e7d4c","imei":"352460074750977","is_limit_ad_tracking":"0","hive_country":"KR","timezone":null,"game_language":"ko","server_id":"KR","analytics_id":"gjkDXPyQNYaWQ5bNf6qqdg=="}}}
*/

// [4]
// showCustomViewWithData 라는 예제 메서드를 구현한 예
// (showCustomViewWithData 메서드는 커스텀뷰를 자체 구성한 데이터로 호출하는 역할을 합니다.)
public void showCustomViewWithData()
{
activity.runOnUiThread(new Runnable() {

@Override
public void run() {
JSONObject jsonData = new JSONObject();

// TODO : 게임앱에서 customview 노출 시 필요한 데이터를 셋팅합니다.
// 그리고 추가로 Android Mercury v2.12.6 이상을 쓰는 경우 mercuryGetCustomViewInfo API에서 응답받은 cookies 데이터를 넣어주어야 합니다.

try {
jsonData.put(“cookies”, cookiesJson); // 추가로 cookies 데이터를 셋팅, 가장 상위 depth에 cookies키가 존재하면 됩니다.
}
catch (Exception e) {
e.printStackTrace();
}

// “웹뷰에서 커스텀 뷰를 노출합니다.”
// Webview 객체 구현 생략
// targetURL는 커스텀 뷰 호출에 사용되는 GCP 프로모션 서버와 약속된 프로토콜 url 입니다.
webView.postUrl(targetURL, jsonData.toString().getBytes());

}
});
}

void mercuryCallBack(int result)

Description
iOS / Wrapper, Android의 callback 함수 예제입니다.
Return Value

no return value

Parameter

in/out	Type	Name	Description
in	int	result	Mercury callback

Remark
not comment
Sample Code

// Android mercury callback 함수 예시

@Override
public void mercuryCallBack(int result) {
switch(result)
{
case Mercury.MERCURY_OPEN:
{
Toast.makeText(MainActivity.this, "MERCURY_OPEN", Toast.LENGTH_SHORT).show();
Log.d("Mercury", "MERCURY_OPEN");
break;
}
case Mercury.MERCURY_CLOSE:
{
Toast.makeText(MainActivity.this, "MERCURY_CLOSE", Toast.LENGTH_SHORT).show();
Log.d("Mercury", "MERCURY_CLOSE");
break;
}
case Mercury.MERCURY_FORCED_OPEN:
{
Toast.makeText(MainActivity.this, "MERCURY_FORCED_OPEN", Toast.LENGTH_SHORT).show();
Log.d("Mercury", "MERCURY_FORCED_OPEN");
break;
}
case Mercury.MERCURY_FORCED_CLOSE:
{
Toast.makeText(MainActivity.this, "MERCURY_FORCED_CLOSE", Toast.LENGTH_SHORT).show();
Log.d("Mercury", "MERCURY_FORCED_CLOSE");
break;
}
case Mercury.MERCURY_NETWORK_DISCONNECT:
{
mActivity.runOnUiThread(new Runnable() {

@Override
public void run() {
AlertDialog.Builder builder = new AlertDialog.Builder(mActivity);
builder.setTitle("Network Disconnection");
builder.setMessage("Network was Disconnection.");
builder.setCancelable(false);
builder.setPositiveButton("OK", null);
builder.create().show();
}
});
break;
}
case Mercury.MERCURY_VIDEO_PROMOTION_START:
{
Toast.makeText(MainActivity.this, "MERCURY_START_PLAYBACK", Toast.LENGTH_SHORT).show();
Log.d("Mercury", "MERCURY_START_PLAYBACK");
// set game sound volume off
break;
}
case Mercury.MERCURY_VIDEO_PROMOTION_FINISH:
{
Toast.makeText(MainActivity.this, "MERCURY_FINISH_PLAYBACK", Toast.LENGTH_SHORT).show();
Log.d("Mercury", "MERCURY_FINISH_PLAYBACK");
// set game sound volume on
break;
}
default:
break;
}
}

목차

상수 및 자료형

MERCURY_RESULT

MERCURY_CUSTOM_RESULT

MERCURY_SHOW_TYPE

MERCURY_BADGE_TARGET

MERCURY_BADGE_TARGET

Mercury (Java source / C# source only)

함수

void CS_MercurySetCallBack(MercuryCB callback)

void CS_MercuryShowEx(const char* uid, MERCURY_SHOW_TYPE mercuryShowType, const char* additionalInfo)

int CS_MercuryGetCustomViewInfo(const char* uid, int viewID, MercuryCBWIthData customViewCallback)

int CS_MercuryShowReviewPopup(const char* uid, const char* vid, const char* did)

int CS_MercuryShowNativeReviewPopup(const char* uid, const char* vid, const char* did)

int CS_MercuryShowMoregamesPopup(const char* uid, const char* vid, const char* did)

void CS_MercurySetUid(const char* uid)

void CS_MercurySetIsUsingStaging(int isUsingStaging)

void CS_MercurySetLog(int isLog)

const char* CS_MercuryGetVersion()

void CS_MercuryGetBadge(const int badgeTarget)

int CS_MercuryGetBadgeType(const int badgeTarget)

int CS_MercuryRequestUAInfo(const char* uid, const char* additionalInfo, MercuryCBWithData callbackWithData)

int CS_MercuryRequestUALinkShare(const char* urlLink, const char* shareMessage)

int CS_MercuryGetBannerInfo(const char* campaignType, const char* bannerType, MercuryCBWithData bannerInfoCallback)

java / C# only

Mercury(Activity activity)

String getVersion()

void CS_MercuryInitImageLoader()

콜백 함수

typedef void (*MercuryCB)(MERCURY_RESULT result)

typedef void (*MercuryCBWithData)(MERCURY_RESULT result, const char* additionalInfo)

void mercuryCallBack(int result)

typedef void (MercuryCBWithData)(MERCURY_RESULT result, const char additionalInfo)