HivePromotion API 레퍼런스 가이드

상수 및 자료형

CSPromotionViewType

* HivePromotion PromotionViewType     typedef  enum _C2PromotionViewType     {         // for showPromotion API         CS_PROMOTION_BANNERLEGACY                = -1,        // 전면 배너 (웹뷰 타입)         CS_PROMOTION_BANNER                              = 0,         // 전면 배너 (이미지 타입)         CS_PROMOTION_NEWS,                                                 // 새소식 페이지         CS_PROMOTION_NOTICE,                                               // HIVE 공지사항             } CSPromotionViewType;

CSPromotionCustomType

* HivePromotion PromotionCustomType     typedef  enum _C2PromotionCustomType     {         // for showCustomContents API         CS_PROMOTION_VIEW                = 0,        // 커스텀 뷰         CS_PROMOTION_BOARD                           // 커스텀 보드         CS_PROMOTION_SPOT,                             // 스팟 배너         CS_PROMOTION_DIRECT,                          // 다이렉트 뷰             } C2PromotionCustomType;

CSPromotionResult

* HivePromotion CSPromotionResult     typedef  enum _CSPromotionResult     {         // for result Open/Close         CS_PROMOTION_RESULT_NEWS_OPEN                = 0,        // 커스텀 뷰         CS_PROMOTION_RESULT_NEWS_CLOSE                             // 커스텀 보드         CS_PROMOTION_RESULT_NOTICE_OPEN,                             // 스팟 배너         CS_PROMOTION_RESULT_NOTICE_CLOSE,                           // 다이렉트 뷰                 CS_PROMOTION_RESULT_BANNER_OPEN,                         // 프로모션 뷰(BANNER)가 열렸을 때         CS_PROMOTION_RESULT_BANNER_CLOSE,               // 프로모션 뷰(BANNER)가 닫혔을 때                 CS_PROMOTION_RESULT_CUSTOM_VIEW_OPEN,           // 프로모션 뷰(CUSTOM_VIEW)가 열렸을 때         CS_PROMOTION_RESULT_CUSTOM_VIEW_CLOSE,          // 프로모션 뷰(CUSTOM_VIEW)가 닫혔을 때                 CS_PROMOTION_RESULT_CUSTOM_BOARD_OPEN,          // 프로모션 뷰(CUSTOM_BOARD)가 열렸을 때         CS_PROMOTION_RESULT_CUSTOM_BOARD_CLOSE,         // 프로모션 뷰(CUSTOM_BOARD)가 닫혔을 때                 CS_PROMOTION_RESULT_SPOT_OPEN,                  // 프로모션 뷰(SPOT)가 열렸을 때         CS_PROMOTION_RESULT_SPOT_CLOSE,                 // 프로모션 뷰(SPOT)가 닫혔을 때                 CS_PROMOTION_RESULT_DIRECT_OPEN,                // 프로모션 뷰(DIRECT)가 열렸을 때         CS_PROMOTION_RESULT_DIRECT_CLOSE,               // 프로모션 뷰(DIRECT)가 닫혔을 때                 CS_PROMOTION_RESULT_OFFERWALL_OPEN,             // 오퍼월 뷰가 열렸을 때         CS_PROMOTION_RESULT_OFFERWALL_CLOSE,            // 오퍼월 뷰가 닫혔을 때                 CS_PROMOTION_RESULT_REVIEW_OPEN,                // REVIEW 팝업이 열렸을 때         CS_PROMOTION_RESULT_REVIEW_CLOSE,               // REVIEW 팝업이 닫혔을 때                 CS_PROMOTION_RESULT_MORE_GAMES_OPEN,            // MORE_GAMES 팝업이 열렸을 때 (AD only)         CS_PROMOTION_RESULT_MORE_GAMES_CLOSE,           // MORE_GAMES 팝업이 닫혔을 때 (AD only)         CS_PROMOTION_RESULT_MORE_GAMES_EXIT,            // MORE_GAMES 팝업 버튼중 종료 버튼을 눌렀을 때 (AD only)                 CS_PROMOTION_RESULT_START_PLAYBACK,             // 프로모션 동영상이 시작될때         CS_PROMOTION_RESULT_FINISH_PLAYBACK,            // 프로모션 동영상이 종료될때             CS_PROMOTION_RESULT_NEWS_GOBACK,                // 프로모션 뷰(NEWS)가 GoBack스킴 전달 받았을 때     CS_PROMOTION_RESULT_NOTICE_GOBACK,              // 프로모션 뷰(NOTICE)가 GoBack스킴 전달 받았을 때     CS_PROMOTION_RESULT_CUSTOM_VIEW_GOBACK,     // 프로모션 뷰(CUSTOM_VIEW)가 GoBack스킴 전달 받았을 때     CS_PROMOTION_RESULT_CUSTOM_BOARD_GOBACK,        // 프로모션 보드(CUSTOM_BOARD)가 GoBack스킴 전달 받았을 때     CS_PROMOTION_RESULT_SPOT_GOBACK,                    // 프로모션 뷰(SPOT)가 GoBack 스킴 전달 받았을 때     CS_PROMOTION_RESULT_DIRECT_GOBACK,              // 프로모션 뷰(DIRECT)가 GoBack 스킴 전달 받았을 때     CS_PROMOTION_RESULT_OFFERWALL_GOBACK,           // 오퍼월 뷰가 GoBack 스킴 전달 받았을 때     } CSPromotionResult;

CSOfferwallState

* HivePromotion OfferwallState     typedef  enum _CSOfferwallState     {         //         CS_OFFERWALL_STATE_ENABLED = 0,     // 오퍼월 활성화 상태         CS_OFFERWALL_STATE_DISABLED,            // 오퍼월 비활성화 상태         CS_OFFERWALL_STATE_UNKNOWN,         // 오퍼월 상태 확인 불가             } CSOfferwallState;

CSPromotionAPICallResult

* HivePromotion PromotionAPICallResult     typedef  enum _CSPromotionAPICallResult     {         // 에러 코드         CS_PROMOTION_SUCCESS                = 0,         CS_PROMOTION_INVALID_PARAM      = -1,         CS_PROMOTION_NOT_SUPPORTED      = -2,         CS_PROMOTION_IN_PROGRESS            = -3,         CS_PROMOTION_TIMEOUT                = -4,         CS_PROMOTION_NETWORK            = -5,         CS_PROMOTION_CANCELED           = -6,         CS_PROMOTION_NEED_INITIALIZE        = -7,         CS_PROMOTION_RESPONSE_FAIL      = -8,         CS_PROMOTION_INVALID_SESSION        = -9,         CS_PROMOTION_NEED_RESTORE       = -10,         CS_PROMOTION_RESTORE_NOT_OWNED  = 10,         CS_PROMOTION_UNKNOWN            = -99             } CSPromotionAPICallResult;

함수

void CS_PromotionInitialize()

• Description

  HivePromotion 모듈을 초기화 합니다.

• Return Value

void

• Remark

  Android Native : init
  Unity Plugin(C#) : PromotionInitialize

void CS_PromotionShow(CSPromotionViewType type, int isForced, const char* uid, CSPromotionViewHandler handler)

• Description

  전면 배너, 새소식, 공지사항 배너를 노출합니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	CSPromotionViewType	type	CSPromotionViewType을 설정
in	int	isForced	오늘 하루 안보기가 없는 페이지 여부 설정
in	const char*	uid	로그인한 유저의 uid
in	CSPromotionViewHandler	handler	프로모션 뷰 노출 결과 콜백

• Remark

  Android Native : showPromotion
  Unity Plugin(C#) : CS_UnityPromotionShow

void CS_PromotionShowCustom(CSPromotionViewType type, const char* contents, const char* uid, CSPromotionViewHandler handler)

• Description

  전면 배너, 새소식, 공지사항 배너를 노출합니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	CSPromotionViewType	type	CSPromotionViewType을 설정
in	const char*	contents	커스텀 컨텐츠 id
in	const char*	uid	유저의 uid
in	CSPromotionViewHandler	handler	프로모션 뷰 노출 결과 콜백

• Remark

  Android Native : showCustomContents
  Unity Plugin(C#) : CS_UnityPromotionShowCustom

CSOfferwallState CS_GetOfferwallState()

• Description

  오퍼월 등록 상태를 확인합니다.

• Return Value

CSOfferwallState

• Remark

  Android Native : getOfferwallState
  Unity Plugin(C#) : CS_GetOfferwallState

void CS_ShowOfferwall(const char* uid, CSPromotionViewHandler handler)

• Description

  전면 배너, 새소식, 공지사항 배너를 노출합니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	uid	유저의 uid
in	CSPromotionViewHandler	handler	프로모션 뷰 노출 결과 콜백

• Remark

  Android Native : showOfferwall
  Unity Plugin(C#) : CS_UnityShowOfferwall

void CS_ShowReview(const char* uid, CSPromotionViewHandler handler)

• Description

  리뷰 팝업을 노출합니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	uid	유저의 uid
in	CSPromotionViewHandler	handler	프로모션 뷰 노출 결과 콜백

• Remark

  Android Native : showReview
  Unity Plugin(C#) : CS_UnityShowReview

void CS_ShowReview(const char* uid, CSPromotionViewHandler handler)

• Description

  iOS의 네이비브 리뷰 팝업을 노출합니다. Android의 경우 CS_ShowReview 호출과 동일한 기능을 합니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	uid	유저의 uid
in	CSPromotionViewHandler	handler	프로모션 뷰 노출 결과 콜백

• Remark

  Android Native : showNativeReview
  Unity Plugin(C#) : CS_ShowNativeReview

void CS_ShowExit(const char* uid, CSPromotionViewHandler handler)

• Description

  Android 종료 팝업을 노출합니다. iOS에서는 기능이 수행되지 않습니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	uid	유저의 uid
in	CSPromotionViewHandler	handler	프로모션 뷰 노출 결과 콜백

• Remark

  Android Native : showReview
  Unity Plugin(C#) : CS_UnityShowReview

void CS_GetViewInfo(CSPromotionCustomType type, const char* contents, const char* uid, CSPromotionInfoHandler handler)

• Description

  프로모션 커스텀 컨텐츠에 대한 정보를 가져옵니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	CSPromotionCustomType	type	CSPromotionCustomType을 설정
in	const char*	contents	커스텀 컨텐츠 id
in	const char*	uid	유저의 uid
in	CSPromotionInfoHandler	handler	프로모션 뷰 정보 호출 결과 콜백

• Remark

  Android Native : getViewInfo
  Unity Plugin(C#) : CS_UnityGetViewInfo

void CS_GetBadgeInfo(const char* uid, CSPromotionBadgeHandler handler)

• Description

  프로모션 뱃지에 대한 정보를 가져옵니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	uid	유저의 uid
in	CSPromotionBadgeHandler	handler	프로모션 뱃지 정보 호출 결과 콜백

• Remark

  Android Native : getBadgeInfo
  Unity Plugin(C#) : CS_UnityGetBadgeInfo

void CS_PromotionGetBannerInfo(const char* campaignType, const char* handler, const char* uid, CSPromotionBannerHandler handler)

• Description

  프로모션 뷰의 배너 정보를 가져옵니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	campaignType	캠패인 타입 (all : 모든 타입, event : 이벤트 타입, notice : 공지 타입, cross : 크로스 타입(C2S.20.3.2 이상), 기타 커스텀 값)
in	const char*	bannerType	배너 타입 (great : 전변 배너, small : 일반 배너, rolling : 롤링 배너, 기타 커스텀 값)
in	const char*	uid	유저의 uid
in	CSPromotionBannerHandler	handler	프로모션 배너 정보 호출 결과 콜백

• Remark

  Android Native : getBannerInfo
  Unity Plugin(C#) : CS_UnityPromotionGetBannerInfo

void CS_PromotionGetAppInvitationData(const char* uid, CSPromotionAppInvitationDataHandler handler)

• Description

  프로모션 집객 App Invitation 정보를 가져옵니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	uid	유저의 uid
in	CSPromotionAppInvitationDataHandler	handler	프로모션 집객 App Invitation 정보 호출 결과 콜백

• Remark

  Android Native : getAppInvitationData
  Unity Plugin(C#) : CS_UnityPromotionGetAppInvitationData

void CS_PromotionShowUAShare(const char* inviteMessage, const char* inviteLink, CSPromotionShareHandler handler)

• Description

  프로모션 집객 App Invitation 정보를 가져옵니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	inviteMessage	초대 메시지
in	const char*	inviteLink	초대 링크
in	CSPromotionShareHandler	handler	프로모션 집객 초대 공유 결과 콜백

• Remark

  Android Native : showUAShare
  Unity Plugin(C#) : CS_UnityPromotionShowUAShare

void CS_SetAdditionalInfo(const char* additionalInfo)

• Description

  프로모션에 사용되는 additionalInfo 값을 설정합니다.

• Return Value

void

• Parameter

in/out	Type	Name	Description
in	const char*	additionalInfo	additionalInfo 데이터

• Remark

  Android Native : setAdditionalInfo
  Unity Plugin(C#) : CS_SetAdditionalInfo

void CS_UpdatePromotionData()

• Description

  프로모션 새소식 페이지에 노출되는 컨텐츠 정보를 갱신합니다. CS_PromotionIntialize 과정에서 내부에서 알아서 호출되나 앱을 재시작하지 않고 유저가 로그아웃 및 로그인하여 변경되었거나 game_language, server_id 정보가 변경되었을 경우 등 모듈과 관련된 정보가 바뀌었을 경우 호출해야 현재 상황에 맞추어 새소식 페이지가 노출됩니다. (새소식 페이지가 열려있지 않은 상태에서 호출합니다.)

• Return Value

void

• Remark

  Android Native : updatePromotionData
  Unity Plugin(C#) : CS_UpdatePromotionData

const char* CS_HivePromotionGetVersion()

• Description

  HivePromotion의 버전 정보를 반환합니다.

• Return Value

const char*

• Remark

  Available in Android HivePromotion 4.15.2, iOS HivePromotion 4.15.2

  Android Native : String getVersion()

  Unity Plugin(C#) : string GetVersion()

콜백 함수

typedef void (*C2PromotionViewHandler)(C2SPromotionAPICallResult result, C2PromotionResult resultType)

• Description

  프로모션 뷰가 노출되는 API 들의 호출 결과

• Return Value

typedef void

• Parameter

in/out	Type	Name	Description
in	C2SPromotionAPICallResult	result	callback
in	C2PromotionResult	resultType	callback

• Remark

  Android Native : PromotionViewListener
  Unity Plugin(C#)(C2SHIVEPromotionPlugin.cs) : IHIVEPromotionViewCallback

• Sample Code

// 응답 코드 확인

typedef void (*CSPromotionInfoHandler)(CSPromotionAPICallResult result, const char* viewInfo)

• Description

  프로모션 뷰의 정보 조회 결과, 뷰 정보를 프로모션 서버에 요청 시 postString을 key로하여 이하 데이터를 한 묶음의 String 타입으로 구성 후 POST 데이터 통신으로 요청

• Return Value

typedef void

• Parameter

in/out	Type	Name	Description
in	CSPromotionAPICallResult	result	callback
in	const char*	viewInfo	json string

• Remark

  Android Native : PromotionViewInfoListener
  Unity Plugin(C#)(C2SHIVEPromotionPlugin.cs) : IHIVEPromotionInfoCallback

• Sample Code

// json string (JSONArray 형태로 전달됨) [     {         "postString":{             "user":{                 "uid":"123456789",                 "vid":"123456789",                 "world":"KR",                 "did":"5027104881",                 "mcc":"450",                 "advertising_id":"9f1ee074-4757-4eca-8bfa-9205aba2ad66",                 "imei":"352460074750977",                 "is_limit_ad_tracking":0,                 "width":"1080",                 "height":"1920",                 "device":"SM-N920K",                 "os_version":"7.0",                 "hive_country":"KR",                 "device_country":"kr",                 "timezone":{                     "ip":"220.70.82.100",                     "zone_id":0,                     "country_code":"KR",                     "zone_name":"Asia\/Seoul",                     "country_name":"South Korea",                     "abbreviation":"",                     "gmt_offset":0,                     "dst":0                 },                 "language":"ko",                 "game_language":"ko",                 "server_id":"KR",                 "analytics_id":"DOiMpPP337laTbBAUDJonw==",                 "app_version":"1.19.0"             },             "game":{                 "appid":"com.com2us.hivesdk.normal.freefull.google.global.android.common",                 "app_version":"1.19.0",                 "app_versioncode":1190,                 "lib_version":"4.4.0",                 "additionalinfo":""             },             "promotion":{                 "content_key":"310000",                 "pid":208625,                 "type_webview":"custom_view",                 "forced":"on"             }         },         "url":"https:\/\/promotion.qpyou.cn\/custom\/view"     } ]

typedef void (*CSPromotionBadgeHandler)(CSPromotionAPICallResult result, const char* badgeInfo)

• Description

  프로모션 배지 정보 조회 결과

• Return Value

typedef void

• Parameter

in/out	Type	Name	Description
in	CSPromotionAPICallResult	result	callback
in	const char*	badgeInfo	json string

• Remark

  Android Native : PromotionBadgeInfoListener
  Unity Plugin(C#)(C2SHIVEPromotionPlugin.cs) : IHIVEPromotionBadgeCallback

• Sample Code

// json string (JSONArray 형태로 전달됨) [     {         "badgeType":"new",         "contentsKey":"123",         "target":"CUSTOMVIEW"     },     {         "badgeType":"new",         "contentsKey":"310000",         "target":"CUSTOMVIEW"     } ]

typedef void (*CSPromotionBannerHandler)(CSPromotionAPICallResult result, const char* bannerInfo)

• Description

  프로모션 배너 정보 조회 결과

• Return Value

typedef void

• Parameter

in/out	Type	Name	Description
in	CSPromotionAPICallResult	result	callback
in	const char*	bannerInfo	json string

• Remark

  Android Native : GetBannerInfoListener
  Unity Plugin(C#)(C2SHIVEPromotionPlugin.cs) : IHIVEPromotionBannerCallback

• Sample Code

// json string (JSONArray 형태로 전달됨) [     {         "pid":254529,         "imageUrl":"https:\/\/image-glb.qpyou.cn\/hivepromotion\/banner\/2012\/2724_1606887906253_test001_960_en.jpg",         "linkUrl":"https:\/\/promotion.qpyou.cn\/news\/direct\/254529",         "displayStartDate":"2020-12-02 14:44:00",         "displayEndDate":"2020-12-31 14:44:00",         "utcStartDate":1606887840,         "utcEndDate":1609393440,         "typeLink":"webview",         "interworkData":null,         "typeBanner":"small"     },     {         "pid":"223196",         "imageUrl":"https:\/\/image-glb.qpyou.cn\/hivepromotion\/banner\/1808\/1036_1533796460_banner_land_inner.png",         "linkUrl":"https:\/\/promotion.qpyou.cn\/news\/direct\/223196",         "displayStartDate":"2020-04-01 17:00:00",         "displayEndDate":"2033-08-13 15:33:00",         "utcStartDate":1585728000,         "utcEndDate":2007527580,         "typeLink":"webview",         "interworkData":null,         "typeBanner":"small"     } ]

typedef void (*CSPromotionAppInvitationDataHandler)(CSPromotionAPICallResult result, const char* appInvitationData)

• Description

  프로모션 집객 App Invitation 정보 조회 결과

• Return Value

typedef void

• Parameter

in/out	Type	Name	Description
in	CSPromotionAPICallResult	result	callback
in	const char*	appInvitationData	json string

• Remark

  Android Native : AppInvitationDataListener
  Unity Plugin(C#)(C2SHIVEPromotionPlugin.cs) : IHIVEPromotionAppInvitationDataCallback

• Sample Code

// json string {     "inviteCommonLink":"http:\/\/ua.withhive.com\/ko\/ua1853167c?t=1601347972",     "inviteHivemsgLink":"http:\/\/ua.withhive.com\/ko\/ua1853167h?t=1601347972",     "inviteFacebookLink":"http:\/\/ua.withhive.com\/ko\/ua1853167f?t=1601347972",     "qrcode":"89504e470d0a1a0a00000...(생략)...",    // hex string 형태이며 별도의 형태로 변환하여 이미지화 가능     "eachCampaigns":     [         {             "title":"건별 달 성 제목",             "description":"건별 달성 설명",             "imageUrl":"https:\/\/image-glb.qpyou.cn\/hivepromotion\/ua\/1508828309_ko.png",             "item":             {                 "gem":50             },             "count":0,             "limit":500         }     ],     "stageCampaigns":     [         {             "title":"제목",             "description":"문구",             "imageUrl":"https:\/\/image-glb.qpyou.cn\/hivepromotion\/ua\/1508827179_ko.png",             "item":             {                 "gem":500             },             "count":0,             "limit":100         }     ],     "originalJson":"{\"result_code\":200,\"result_message\":\"success\",\"invite_message\":\"HIVE SDK \\ub97c     \\ub2e4\\uc6b4\\ub85c\\ub4dc \\ud574\\uc8fc\\uc138\\uc694.\",\"invite_link\":     {\"common\":\"http:\\\/\\\/ua.withhive.com\\\/ko\\\/ua1853167c?     t=1601347972\",\"facebook\":\"http:\\\/\\\/ua.withhive.com\\\/ko\\\/ua1853167f?     t=1601347972\",\"hivemsg\":\"http:\\\/\\\/ua.withhive.com\\\/ko\\\/ua1853167h?     t=1601347972\",\"qrcode\":\"89504e470d0a1...(생략)...\"},\"campaigns\":{\"each\":[{\"title\":\"\\uac74\\ubcc4 \\ub2ec     \\uc131 \\uc81c\\ubaa9\",\"description\":\"\\uac74\\ubcc4 \\ub2ec\\uc131     \\uc124\\uba85\",\"img\":\"https:\\\/\\\/image-     glb.qpyou.cn\\\/hivepromotion\\\/ua\\\/1508828309_ko.png\",\"type\":\"each\",\"item\":     {\"gem\":50},\"count\":0,\"limit\":500}],\"stage\":     [{\"title\":\"\\uc81c\\ubaa9\",\"description\":\"\\ubb38\\uad6c\",\"img\":\"https:\\\/\\\/image-     glb.qpyou.cn\\\/hivepromotion\\\/ua\\\/1508827179_ko.png\",\"goal\":{\"count\":0,\"total\":4},\"type\":\"stage\",\"item\":{     \"gem\":500},\"count\":0,\"limit\":100}]}}" }

typedef void (*CSPromotionShareHandler)(CSPromotionAPICallResult result)

• Description

  프로모션 집객 App Invitation 정보 조회 결과

• Return Value

typedef void

• Parameter

in/out	Type	Name	Description
in	CSPromotionAPICallResult	result	callback

• Remark

  Android Native : PromotionShareListener
  Unity Plugin(C#)(C2SHIVEPromotionPlugin.cs) : IHIVEPromotionShareCallback

• Sample Code

// 응답 코드 확인