Hive User Engagement (UE) provides deep link function with coupons, which allows to invite game users to a specific location or event page in games with a simple tap of the link, or to get rewards directly.
In Hive, the action you want to perform through scheme URL is called user engagement action. When game performs the action specified in the given URL, Hive requests to the game in the form of a user engagement event.
What is User Engagement?
UE is a service which performs requests from inside and outside of the application, and performs the following functions:
- Perform scheme URL from outside of the app through deep link or push notification.
- Perform scheme URL from inside of the app through interwork.
- With Hive SDK v4.4.0 and later,
- Send the access history to game app via external route such as QR codes and links created by User Acquisition to request rewards.
- Send the access history to game app via offerwall or other functions of Hive to request rewards. (Request for CPI rewards)
- Ensure that Game Client implement
setEngagementReadyAPI and send the request when Hive module is available to perform the function of UE to process CPI rewards and others.
How to Indicate Scheme URL on Hive
Scheme URL is a format to express the action of UE. It indicates what action is defined in the Scheme URL and who it is applied to. Hive-using Scheme URL follows a standard format so-called Uniform Resource Identifier (URI), and composes of service field and common field.
- Standard format: {scheme}://{host}/{path}?{query}
- Hive format: {scheme}://{host}/{api}?{parameters}
Service field: {scheme}://{host} | Common field: /{api}?{parameters}
Hive format indicates an event that processes on Hive SDK and includes the given {api} as shown in the Common Field section. For this reason, the common field of the Hive format composes of
/{api}?{parameters}in place of/{path}?{query}of a standard format. For a list of {api} that includes on Hive format, see Common Field.
Using Scheme URL in Games
In addition to using UE for coupon deep linking purposes, if you need to move to a specific location in games (e.g., dungeon, gift box, shop, etc.) for your promotional purposes, ensure to define the path in the game, and provide Scheme URL. This Scheme URL is converted to a landing URL on Hive Console, and then delivered to the user.
For more information about the scheme URL in games, see If the host of Scheme URL is game.
Service Field
Service field of Scheme URL is {scheme}://{host}, which indicates the path that the deep link is delivered to the Hive SDK and composes of scheme and host.
scheme
There are three paths where URLs are passed to the app:
Push
Whether or not the game app targeted by the Scheme URL is running, the URL recipient will receive a push message that contains the Scheme URL. When the receiver taps the message, Push Scheme URL is sent to Hive Client, and then Hive Client processes the URL.
-
- e.g., push://{host}/{path}?{query}
Deep Link
If user taps a URL via external means such as text messages, and web browser, and if the scheme field of this URL is filled with the AppID of a specific game on the user device, the game is executed and the URL is delivered to Hive SDK. In case the game app is not installed, it move to installation page.
-
- e.g., com.com2us.example://{host}/{path}?{query}
The user follows is different depending on the status of game installation when using deep link scheme.
- If the game is installed
When tapping the deep link, the user checks game tips first, and moves to the game.
- If the game is not installed
When user taps the link in a message, it notifies the rewards are available after game installation. Since the game is not installed, it will be moved to Download Market (Google Play Store / Apple App Store).
Interwork
If a user touch the specific link URL of the Promotion screen (Banner, Notice, etc.) of the Hive SDK while the app is running, and the scheme field of that URL is “interwork“, the URL is delivered to Hive SDK.
-
- e.g., interwork://{host}/{path}?{query}
You can call the request for processing interwork scheme by using processURI API to send URL from game to Hive SDK directly.
Unity®
|
1 2 3 4 5 6 7 8 9 10 |
String uri = ""; Boolean result = Promotion.processURI(uri); if(result) { // Success in registration of UE Event } else { // Unsuitable format for Hive Scheme URI } |
C++
|
1 2 3 4 5 6 7 8 9 10 |
std::string uri = ""; bool result = Promotion::processURI(uri); if(result) { // Success in registration of UE Event } else { // Unsuitable format for Hive Scheme URI } |
Android
|
1 2 3 4 5 6 7 8 9 10 |
String uri = ""; boolean result = Promotion.processURI(uri); if(result) { // Success in registration of UE Event } else { // Unsuitable format for Hive Scheme URI } |
iOS
|
1 2 3 4 5 6 7 8 9 10 |
NSString* uri = @""; bool result = [HIVEPromotion processURI:uri]; if(result) { // Success in registration of UE Event } else { // Unsuitable format for Hive Scheme URI } |
Host
Host specifies who is responsible for the action requested:
-
- game: Action which the game is responsible for
- hive: Action which Hive SDK is responsible for
Common Field
Common field of Scheme URL is /{api}/{parameters}, which indicates the action to process including required information:
api clarifies what action to take through the URL. The following actions can be taken depending on the host:
If the host of Scheme URL is hive
Be aware that available API is different depending on authentication version, v4 or v1.
| API | Implementation | Auth v4 | Auth v1 |
| authlogin auth/login |
Hive membership login (Guest -> Verified account) | X | O |
| socialinquiry social/inquiry |
Access to Hive 1:1 inquiry page | O | O |
| promotionshow promotion/show |
Promotion custom view exposure | O | O |
| promotioncoupon promotion/coupon |
Processed the promotion coupon as used | O | O |
| offerwallshow promotion/offerwall |
Offerwall exposure | O | O |
| iappromote | Item purchase reservation (Hive SDK v4.5.0 and later with Hive IAP v4) | O | O |
| iappurchase | Item purchase on spot banner (Hive SDK v4.5.0 and later with Hive IAP v4) When implementing iappurchase, setEngagementReady() becomes false automatically. After purchase, you need to set setEngagementReady() as true |
O | O |
| social/myinquiry | Access to Hive My Inquiry page | O | O |
| social/profile | Access to profile page | O | O |
Hive receives notifications before and after the process relevant to UE through EngagementListener. The game may require work such as pausing the game as needed.
For more about iappromote and iappurchase, see the contents below.
iappromote
Hive IAP v4 with Hive SDK v4.5.0 and later supports this feature. It provides purchase reservation for users before executing a game. The feature functions the same with Promotional IAP provided by iOS 11, and supports android-base environment. iappromote is available on event pages, push services and messages.
- When user clicks scheme URL via event pages, push services and messages, gain the purchase data by executing the game.
- Call the iappromote scheme and receive
EngagementEventType.IAP_PROMOTEas a result data. With the result value, implement checkPromotePurchase API to gain the market PID. You can continue the purchase process when implementing purchase API with the market PID you get as a reference. - iappromote is available for both on iOS and Android.
- Structure of the scheme URL: [AppID/push/interwork]://hive/iappromote?marketpid=[marketpid]
- e.g.,
- interwork://hive/iappromote?marketpid=com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs02
- Replace the part in red to the market PID related to the reserved purchase.
iappurchase
Hive IAP v4 with Hive SDK v4.5.0 and later supports this feature. You can sell items on the spot banner by using the iappurchase in the scheme URL.
- If you call the iappurchase shceme, purchase logic is implemented. So, make sure to initialize the market and gain the store information prior to executing the scheme. This means, implement
marketConnect APIandgetProductInfo APIbefore changing the state ofsetEngagementReadyas true. - As game executes the logic after purchase, it pauses engagement action (
setEngagementReadybecomes false automatically). - After purchase is complete, change the state of
setEngagementReadyas true to continue the action. - Structure of the scheme URL: [AppID/push/interwork]://hive/iappurchase?marketpid=[marketpid]
- e.g.,
- interwork://hive/iappurchase?marketpid=com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01
- Replace the part in red to the market PID related to the reserved purchase.
Sync iappurchase with Spot Banner
If you want to sell items by using iappurchase scheme, utilize Spot Banner. View the guideline to use Spot Banner
- Set a spot banner ID at a desired location or timing in the game to encourage users to purchase items.
- Call the spot banner ID. When user taps the spot banner, implement interwork scheme. The registered EngagementListener will send the running state of interwork.
- If you call the interwork shceme, purchase logic is implemented. So, make sure to initialize the market and gain the store information prior to executing the scheme. This means, implement
marketConnect APIandgetProductInfo APIbefore calling the spot banner. - As game executes the logic after purchase, it pauses engagement action (
setEngagementReadybecomes false automatically). - After purchase is complete, change the state of
setEngagementReadyas true to continue the action. - Enter the spot banner ID on Hive Console > Promotion > Campaign Settings > Spot Banner, and insert the scheme URL in the internal link. Request how to register a spot banner to Business PM.
- e.g.,
- interwork://hive/iappurchase?marketpid=com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01
- Replace the part in red to the market PID related to the reserved purchase.
- When you register the banner on the console, test the purchase in your game.
If the host of Scheme URL is game
In this case, the game must perform the requested action. Hive SDK is handling Scheme URL, and then send the result as JSONObject format through EngagementListener. The results are divided into the scheme, api, and param key. Make sure that game performs the relevant action in appropriate time after receiving the values.
- e.g., Giving items in postbox
- URL Scheme : com.com2us.example://game/postboxadditem?item_id=123456&item_title=item01
- JSONObject result from Hive SDK
12345{"scheme" : "com.com2us.example","api" : "/postboxadditem","param" : "item_id=123456&item"}
For more details about how to implement UE, see Sample Code of Implementing User Engagement > Declaring and Registering Global Callback.
Project Settings
To use UE in the game app, set by OS before building the app.
Android Settings
Set the launchMode method as singleTask or singleTop. The method is one of Main Activity items in AndroidManifest.xml file.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
//<application android:hardwareAccelerated="true" android:icon="@drawable/app_icon" android:label="@string/app_name" android:isGame="true"> <activity android:label="@string/app_name" android:name="com.hive.sample.MainActivity" android:screenOrientation="sensor" android:launchMode="singleTask" ... |
iOS Settings
- Select the Build of an app you want to develop on the list of Xcode TARGETS.
- Select the Info tab.
- Add Additional url type properties items in URL Types section to input AppID in Bundle Identifier and URL Schemes field.
Implementing User Engagement
Declaring and Registering Global Callback
Declare and register global callback to apply Hive UE. How to declaration and registration depends on the version of Hive SDK.
Hive SDK v4.5.0 and later
You must register global callback using the handler registration API of Promotion class. Followings are sample codes.
Unity®
API Reference: hive.Promotion.setEngagementListener
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 |
using hive; Promotion.setEngagementListener((ResultAPI result, EngagementEventType engagementEventType, EngagementEventState engagementEventState, JSONObject param) => { switch (engagementEventType) { case EngagementEventType.EVENT_TYPE: switch (engagementEventState) { case EngagementEventState.BEGIN: // All actions of Engagement are performed break; case EngagementEventState.FINISH: // All actions of Engagement are completed break; } break; case EngagementEventType.AUTH_LOGIN_VIEW: switch (engagementEventState) { case EngagementEventState.START: // Start Hive membership login page exposure request break; case EngagementEventState.END: // Hive membership login completed (delivered after login completed/window closed) break; } break; case EngagementEventType.SOCIAL_INQUIRY_VIEW: switch (engagementEventState) { case EngagementEventState.START: // Start 1:1 inquiry page exposure request break; case EngagementEventState.END: // 1:1 inquiry page exposure completed (delivered after 1:1 inquiry window is closed) break; } break; case EngagementEventType.PROMOTION_VIEW: switch (engagementEventState) { case EngagementEventState.START: // Start Promotion View impression request break; case EngagementEventState.END: // Promotion View exposure completed (delivered after the Promotion window is closed) break; } break; caseEngagementEventType.COUPON: switch (engagementEventState) { case EngagementEventState.START: // Start coupon consumption request break; case EngagementEventState.END: // Complete coupon consumption request and send response break; } break; case EngagementEventType.OFFERWALL_VIEW: switch (engagementEventState) { case EngagementEventState.START: // Start offer wall page exposure request break; case EngagementEventState.END: // Completed offerwall page exposure (delivered after closing the offerwall window) break; } break; case EngagementEventType.EVENT: // If the host is game, send the JSONObject result value String api = ""; String param = ""; param.GetField(ref api, "api"); param.GetField(ref param, "param"); // Check api and param parsing results by Hive SDK version (differences depending on Hive SDK C# JSONObject version) // ex) interwork://game/openurl?rurl=https://www.withhive.com //Under Hive SDK 4.16.2 // When output to api debug console: \/openurl // ( api.Equals("\\/openurl"); ) // param debug console output: rurl=https:\/\/www.withhive.com // Hive SDK 4.16.2 or higher // When output to api debug console: /openurl // (api.Equals("/openurl"); ) // param debug console output: rurl=https://www.withhive.com // TODO: Perform the following actions according to the api and param values break; case EngagementEventType.IAP_UPDATED: switch (engagementEventState) { case EngagementEventState.EVENT_START: // Signal to accept as purchase history has changed (call Restore() method) break; case EngagementEventState.EVENT_END: // Signal to accept as purchase history has changed (call Restore() method) String type = ""; param.getField(ref type, "type"); if (type == "subscription") { // TODO: restore subscription product IAPV4.restoreSubscription((ResultAPI result, List <hive.IAPV4.IAPV4Receipt> receiptList) => { if (!result.isSuccess()) { return; } // TODO: Request receipt verification using the received receiptList }); return; } // TODO: restore consumable goods IAPV4.restore((ResultAPI result, List <hive.IAPV4.IAPV4Receipt> receiptList) => { if (!result.isSuccess()) { return; } // TODO: Request receipt verification using the received receiptList }); break; } break; case EngagementEventType.IAP_PROMOTE: switch (engagementEventState) { case EngagementEventState.START: // Convey whether IAP Promote data exists break; case EngagementEventState.END: if (!result.isSuccess()) { return; } // Since IAP Promote data exists, marketPid is received through checkPromote API. IAPV4.checkPromotePurchase((ResultAPI promoteResult, String marketPid) => { if (!promoteResult.isSuccess()) { return; } // TODO: Request purchase with the received marketPid item IAPV4.purchase(marketPid, null, (ResultAPI purchaseResult, hive.IAPV4.IAPV4Receipt receipt) => { if (!purchaseResult.isSuccess()) { return; } // TODO: Request receipt verification with received receipt }); }); break; } break; case EngagementEventType.IAP_PURCHASE: switch (engagementEventState) { case EngagementEventState.START: // A pop-up for purchasing items received through the IAPPurchase schema is displayed. break; case EngagementEventState.END: // Whether or not the purchase of the requested item was successful is communicated through the IAPPurchase schema. if (!result.isSuccess()) { return; } String receipt = ""; param.GetField(ref receipt, "iapV4Receipt"); break; } break; case EngagementEventType.SOCIAL_MY_INQUIRY: switch (engagementEventState) { case EngagementEventState.START: // Start my inquiry page exposure request break; case EngagementEventState.END: // My inquiry page has been exposed (delivered after the My Inquiry window is closed) break; } break; case EngagementEventType.SOCIAL_PROFILE: switch (engagementEventState) { case EngagementEventState.START: // Initiate profile page exposure request break; case EngagementEventState.END: // Profile page exposure completed (delivered after closing the profile window) break; } break; } }); |
C++
API Reference: Promotion::setEngagementHandler
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 |
#include <HIVE_SDK_Plugin/HIVE_CPP.h> using namespace std; using namespace hive; Promotion::setEngagementHandler([ = ](ResultAPI const & result, EngagementEventType engagementEventType, EngagementEventState engagementEventState, picojson::value const & param) { switch (engagementEventType) { case EngagementEventType::EVENT_TYPE: switch (engagementEventState) { case EngagementEventState::BEGIN: // All actions of Engagement are performed break; case EngagementEventState::FINISH: // All actions of Engagement are completed break; } break; case EngagementEventType::AUTH_LOGIN_VIEW: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Start Hive membership login page exposure request break; case EngagementEventState::EVENT_END: // Hive membership login completed (delivered after login completed/window closed) break; } break; case EngagementEventType::SOCIAL_INQUIRY_VIEW: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Start 1:1 inquiry page exposure request break; case EngagementEventState::EVENT_END: // 1:1 inquiry page exposure completed (delivered after 1:1 inquiry window is closed) break; } break; case EngagementEventType::PROMOTION_VIEW: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Start Promotion View impression request break; case EngagementEventState::EVENT_END: // Promotion View exposure completed (delivered after the Promotion window is closed) break; } break; case EngagementEventType::COUPON: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Start coupon consumption request break; case EngagementEventState::EVENT_END: // Complete coupon consumption request and send response break; } break; case EngagementEventType::OFFERWALL_VIEW: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Start offer wall page exposure request break; case EngagementEventState::EVENT_END: // Completed offerwall page exposure (delivered after closing the offerwall window) break; } break; case EngagementEventType::EVENT: // If the host is game, send the JSONObject result value if (param == null) { return; } string api = param.get("api").to_str(); string param = param.get("param").to_str(); // TODO: Perform the following actions according to the api and param values break; case EngagementEventType::IAP_UPDATED: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Signal to receive since purchase details have changed break; case EngagementEventState::EVENT_END: // Signal to receive since purchase details have changed string type = param.get("type").to_str(); if (type != null, type == "subscription") { // TODO: restore subscription product IAPV4::restoreSubscription([ = ](ResultApi const & result, vector < reference_wrapper < IAPV4Receipt >> receiptList) { if (!result.isSuccess()) { return; } // TODO: Request receipt verification using the received receiptList }); return; } // TODO: restore consumable goods IAPV4::restore([ = ](ResultAPI const & result, vector < reference_wrapper < IAPV4Receipt >> receiptList) { if (!result.isSuccess()) { return; } // TODO: Request receipt verification using the received receiptList }); break; } break; case EngagementEventType::IAP_PROMOTE: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Convey whether IAP Promote data exists break; case EngagementEventState::EVENT_END: if (!result.isSuccess()) { return; } // Since IAP Promote data exists, marketPid is received through check Promote API. IAPV4::checkPromotePurchase([ = ](ResultApi const & promoteResult, string marketPid) { if (!promoteResult.isSuccess()) { return; } // TODO: Request to purchase the delivered market Pid item IAPV4::purchase(marketPid, "", [ = ](ResultApi const & purchaseResult, IAPV4Receipt const * receipt) { if (!purchaseResult.isSuccess()) { return; } // TODO: Request receipt verification with received receipt }); }); break; } break; case EngagementEventType::IAP_PURCHASE: switch (engagementEventState) { case EngagementEventState::EVENT_START: // A pop-up for purchasing items received through the IAPPurchase schema is displayed. break; case hive::EngagementEventState::EVENT_END: // Whether or not the purchase of the requested item was successful is communicated through the IAPPurchase schema. if (result.isSucces()) { return; } picojson::value receiptJson = param.get("iapV4Receipt"); shared_ptr receipt = IAPV4Receipt::create(receiptJson); break; } break; case EngagementEventType::SOCIAL_MY_INQUIRY: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Start my inquiry page exposure request break; case EngagementEventState::EVENT_END: // My inquiry page has been exposed (delivered after the My Inquiry window is closed) break; } break; case EngagementEventType::SOCIAL_PROFILE: switch (engagementEventState) { case EngagementEventState::EVENT_START: // Initiate profile page exposure request break; case EngagementEventState::EVENT_END: // Profile page exposure completed (delivered after closing the profile window) break; } break; } }); |
Kotlin
API Reference: setEngagementListener
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 |
import com.hive.IAPV4 import com.hive.Promotion import com.hive.ResultAPI Promotion.setEngagementListener(object: Promotion.EngagementListener { override fun onEngagement( result: ResultAPI, engagementEventType: Promotion.EngagementEventType, engagementEventState: Promotion.EngagementEventState, param: JSONObject ? ) { // Code branched from Hive SDK depending on the type of intervention when(engagementEventType) { Promotion.EngagementEventType.EVENT_TYPE -> when(engagementEventState) { Promotion.EngagementEventState.BEGIN -> { // All actions of Engagement are performed } Promotion.EngagementEventState.FINISH -> { // All actions of Engagement are completed } else -> {} } Promotion.EngagementEventType.AUTH_LOGIN_VIEW -> when(engagementEventState) { Promotion.EngagementEventState.START -> { // Start Hive membership login page exposure request } Promotion.EngagementEventState.END -> { // Hive membership login completed (delivered after login completed/window closed) } else -> {} } Promotion.EngagementEventType.SOCIAL_INQUIRY_VIEW -> when(engagementEventState) { Promotion.EngagementEventState.START -> { // Start 1:1 inquiry page exposure request } Promotion.EngagementEventState.END -> { // 1:1 inquiry page exposure completed (delivered after 1:1 inquiry window is closed) } else -> {} } Promotion.EngagementEventType.PROMOTION_VIEW -> when(engagementEventState) { Promotion.EngagementEventState.START -> { // Start Promotion View impression request } Promotion.EngagementEventState.END -> { // Promotion View exposure completed (delivered after the Promotion window is closed) } else -> {} } Promotion.EngagementEventType.COUPON -> when(engagementEventState) { Promotion.EngagementEventState.START -> { // Start coupon consumption request } Promotion.EngagementEventState.END -> { // Complete coupon consumption request and send response } else -> {} } Promotion.EngagementEventType.OFFERWALL_VIEW -> when(engagementEventState) { Promotion.EngagementEventState.START -> { // Start offer wall page exposure request } Promotion.EngagementEventState.END -> { // Completed offerwall page exposure (delivered after closing the offerwall window) } else -> {} } Promotion.EngagementEventType.EVENT -> { // If the host is game, send the JSONObject result value if (param == null) { return } val api = param.optString("api") val param = param.optString("param") // TODO: Perform the following actions according to the api and param values } Promotion.EngagementEventType.IAP_UPDATED -> when (engagementEventState) { Promotion.EngagementEventState.START -> { // Signal to accept as purchase history has changed (call Restore() method) } Promotion.EngagementEventState.END -> { // Signal to accept as purchase history has changed (call Restore() method) val iapUpdateType = param?.optString("type") if (iapUpdateType == "subscription") { // TODO: restore subscription product IAPV4.restoreSubscription(object : IAPV4.IAPV4RestoreListener { override fun onIAPV4Restore( result: ResultAPI, iapv4ReceiptList: ArrayList<IAPV4.IAPV4Receipt>? ) { if (!result.isSuccess) { return } // TODO: Request receipt verification using the received iapv4ReceiptList } }) } else { IAPV4.restore(object : IAPV4.IAPV4RestoreListener { override fun onIAPV4Restore( result: ResultAPI, iapv4ReceiptList: ArrayList<IAPV4.IAPV4Receipt>? ) { if (!result.isSuccess) { return } // TODO: Request receipt verification using the received iapv4ReceiptList } }) } } else -> {} } Promotion.EngagementEventType.IAP_PURCHASE -> when (engagementEventState) { Promotion.EngagementEventState.START -> { // A pop-up for purchasing items received through the IAPPurchase schema is displayed. } Promotion.EngagementEventState.END -> { // Whether or not the purchase of the requested item was successful is communicated through the IAPPurchase schema. if (!result.isSuccess) { return } val iapV4Receipt = param?.optJSONObject("iapV4Receipt") } else -> {} } Promotion.EngagementEventType.SOCIAL_MYINQUIRY_VIEW -> when (engagementEventState) { Promotion.EngagementEventState.START -> { // Start my inquiry page exposure request } Promotion.EngagementEventState.END -> { // My inquiry page has been exposed (delivered after the My Inquiry window is closed) } else -> {} } Promotion.EngagementEventType.SOCIAL_PROFILE_VIEW -> when (engagementEventState) { Promotion.EngagementEventState.START -> { // Initiate profile page exposure request } Promotion.EngagementEventState.END -> { // Profile page exposure completed (delivered after closing the profile window) } else -> {} } else -> {} } } }) |
Java
API Reference: com.hive.Promotion.setEngagementListener
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 |
import com.hive.IAPV4; import com.hive.Promotion; import com.hive.ResultAPI; Promotion.INSTANCE.setEngagementListener((result, engagementEventType, engagementEventState, param) -> { switch (engagementEventType) { case EVENT_TYPE: switch (engagementEventState) { case BEGIN: // All actions of Engagement are performed break; case FINISH: // All actions of Engagement are completed break; } break; case AUTH_LOGIN_VIEW: switch (engagementEventState) { case START: // Start Hive membership login page exposure request break; case END: // Hive membership login completed (delivered after login completed/window closed) break; } break; case SOCIAL_INQUIRY_VIEW: switch (engagementEventState) { case START: // Start 1:1 inquiry page exposure request break; case END: // 1:1 inquiry page exposure completed (delivered after 1:1 inquiry window is closed) break; } break; case PROMOTION_VIEW: switch (engagementEventState) { case START: // Start Promotion View impression request break; case END: // Promotion View exposure completed (delivered after the Promotion window is closed) break; } break; case COUPON: switch (engagementEventState) { case START: // Start coupon consumption request break; case END: // Complete coupon consumption request and send response break; } break; case OFFERWALL_VIEW: switch (engagementEventState) { case START: // Start offer wall page exposure request break; case END: // Completed offerwall page exposure (delivered after closing the offerwall window) break; } break; case EVENT: // If the host is game, send the JSONObject result value if (param == null) return; String api = param.optString("api"); String paramData = param.optString("param"); // TODO: Perform the following actions according to the api and param values break; case IAP_UPDATED: switch (engagementEventState) { case START: // Signal to accept as purchase history has changed (call Restore() method) break; case END: // Signal to accept as purchase history has changed (call Restore() method) if(param == null) return; String iapUpdateType = param.optString("type"); if(iapUpdateType == "subscription") { // TODO: restore subscription product IAPV4.INSTANCE.restoreSubscription((result1, iapv4ReceiptList) -> { if (!result1.isSuccess()) { return; } // TODO: Request receipt verification using the received iapv4ReceiptList }); } else { IAPV4.INSTANCE.restore((result2, iapv4ReceiptList) -> { if (!result2.isSuccess()) { return; } // TODO: Request receipt verification using the received iapv4ReceiptList }); } break; } break; case IAP_PURCHASE: switch (engagementEventState) { case START: // A pop-up for purchasing items received through the IAPPurchase schema is displayed. break; case END: // Whether or not the purchase of the requested item was successful is communicated through the IAPPurchase schema. if(!result.isSuccess() || param == null) return; JSONObject iapV4Receipt = param.optJSONObject("iapV4Receipt"); break; } break; case SOCIAL_MYINQUIRY_VIEW: switch (engagementEventState) { case START: // Start my inquiry page exposure request break; case END: // My inquiry page has been exposed (delivered after the My Inquiry window is closed) break; } break; case SOCIAL_PROFILE_VIEW: switch (engagementEventState) { case START: // Initiate profile page exposure request break; case END: // Profile page exposure completed (delivered after closing the profile window) break; } break; } }); |
Swift
API Reference: setEngagementHandler(_:)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 |
import HIVEService PromotionInterface.setEngagementHandler() { result, engagementEventType, engagementState, param in switchengageEventType { case.type: switch engagementState{ case .begin: // All actions of Engagement are performed case .finish: // All actions of Engagement are completed } case .authLoginView: switch engagementState { case.eventStart: // Start Hive membership login page exposure request case .eventEnd: // Hive membership login completed (delivered after login completed/window closed) } case .socialInquiryView: switch engagementState { case.eventStart: // Start 1:1 inquiry page exposure request case .eventEnd: // 1:1 inquiry page exposure completed (delivered after 1:1 inquiry window is closed) } case .promotionView: switch engagementState { case.eventStart: // Start Promotion View impression request case .eventEnd: // Promotion View exposure completed (delivered after the Promotion window is closed) } case .coupon: switch engagementState { case.eventStart: // Start coupon consumption request case .eventEnd: // Complete coupon consumption request and send response } case .offerwallView: switch engagementState { case.eventStart: // Start offer wall page exposure request case .eventEnd: // Completed offerwall page exposure (delivered after closing the offerwall window) } case.event: // If the host is game, send the JSONObject result value let api = param?["api"] let param = param?["param"] // Perform requested actions according to api and param values case.iapPromote: switch engagementState { case.eventStart: // Convey whether IAP Promote data exists case.eventEnd: if ! result.isSuccess() { return } // Since IAP Promote data exists, marketPid is received through check Promote API. IAPV4Interface.checkPromotePurchase() { promoteResult, marketPid in if !promoteResult.isSuccess() { return } // TODO: Request to purchase the delivered market Pid item IAPV4Interface.purchase(marketPid, additionalInfo: nil) { purchaseResult, receipt in if !purchaseResult.isSuccess() { return } // TODO: Request receipt verification with received receipt } } case.iapUpdated: switch engagementState { case.eventStart: // Signal to receive since purchase details have changed case.eventEnd: // Signal to receive since purchase details have changed if let type = param ? ["type"], type == "subscription" { // TODO: restore subscription product IAPV4Interface.restoreSubscription() { (result, receiptList) in // TODO: Request receipt verification using the received receiptList } return } // TODO: restore consumable goods IAPV4Interface.restore() { (result, receiptList) in // TODO: Request receipt verification using the received receiptList } } case.iapPurchase: switch engagementState { case.eventStart: // A pop-up for purchasing items received through the IAPPurchase schema is displayed. case.eventEnd: // Whether or not the purchase of the requested item was successful is communicated through the IAPPurchase schema. if result.isSuccess() { let receipt = param ? ["iapV4Receipt"]; } } case.socialMyInquiry: switch engagementState { case.eventStart: // Start my inquiry page exposure request case.eventEnd: // My inquiry page has been exposed (delivered after the My Inquiry window is closed) } case.socialProfile: switch engagementState { case.eventStart: // Initiate profile page exposure request case.eventEnd: // Profile page exposure completed (delivered after closing the profile window) } } } |
Objective-C
API Reference: HIVEPromotion setEngagementHandler
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 |
#import <HIVEService/HIVEService-Swift.h> [HIVEPromotion setEngagementHandler: ^(HIVEResultAPI *result, HIVEEngagementEventType engagementEventType, HIVEEngagementEventState engagementState, NSDictionary *param) { switch (engagementEventType) { case HIVEEngagementEventTypeType: switch (engagementState) { case HIVEEngagementStateBegin: // All actions of Engagement are performed break; case HIVEEngagementStateFinish: // All actions of Engagement are completed break; } break; case HIVEEngagementEventTypeAuthLoginView: switch (engagementState) { case HIVEEngagementStateEventStart: // Start Hive membership login page exposure request break; case HIVEEngagementStateEnd: // Hive membership login completed (delivered after login completed/window closed) break; } break; case HIVEEngagementEventTypeSocialInquiryView: switch (engagementState) { case HIVEEngagementStateEventStart: // Start 1:1 inquiry page exposure request break; case HIVEEngagementStateEnd: // 1:1 inquiry page exposure completed (delivered after 1:1 inquiry window is closed) break; } break; case HIVEEngagementEventTypePromotionView: switch (engagementState) { case HIVEEngagementStateEventStart: // Start Promotion View impression request break; case HIVEEngagementStateEnd: // Promotion View exposure completed (delivered after the Promotion window is closed) break; } break; case HIVEEngagementEventTypeCoupon: switch (engagementState) { case HIVEEngagementStateEventStart: // Start coupon consumption request break; case HIVEEngagementStateEnd: // Complete coupon consumption request and send response break; } break; case HIVEEngagementEventTypeOfferwallView: switch (engagementState) { case HIVEEngagementStateEventStart: // Start offer wall page exposure request break; case HIVEEngagementStateEnd: // Completed offerwall page exposure (delivered after closing the offerwall window) break; } break; case HIVEEngagementEventTypeEvent: // If the host is game, send the JSONObject result value if (param == nil) { return; } NSString * api = [param objectForKey: @ "api"]; NSSString * param = [param objectForKey: @ "param"]; // TODO: Perform requested action according to api and param values break; case HIVEEngagementEventTypeIapPromote: switch (engagementState) { case HIVEEngagementStateEventStart: // Convey whether IAP Promote data exists break; case HIVEEngagementStateEventEnd: if (![result isSuccess]) { return; } // Since IAP Promote data exists, marketPid is received through check Promote API. [HIVEIAPV4 checkPromotePurchase: ^ (HIVEResultAPI * promoteResult, NSString * marketPid) { if (![promoteResult isSuccess]) { return; } // TODO: Request to purchase an item using the received market Pid [HIVEIAPV4 purchase: marketPid additionalInfo: nil handler: ^ (HIVEResultAPI * purchaseResult, HIVEIAPV4Receipt * receipt) { if (![purchaseResult isSuccess]) { return; } // TODO: Request verification of receipt with received receipt }]; }]; break; } break; case HIVEEngagementEventTypeIapUpdated: switch (engagementState) { case HIVEEngagementStateEventStart: // Signal to receive since purchase details have changed break; case HIVEEngagementStateEventEnd: // Signal to receive since purchase details have changed NSString * type = [param objectForKey: @ "type"]; if (type != nil && [type isEqualToString: @ "subscription"]) { // TODO: restore subscription product [HIVEIAPV4 restoreSubscription: ^ (HIVEResultAPI * result, NSArray < HIVEIAPV4Receipt * > * receiptList) { // TODO: Request receipt verification using the received receiptList }]; return; } // TODO: restore consumable goods [HIVEIAPV4 restore: ^ (HIVEResultAPI * result, NSArray < HIVEIAPV4Receipt * > * receiptList) { // TODO: Request receipt verification using the received receiptList }]; break; } case HIVEEngagementEventTypeIapPurchase: switch (engagementState) { case HIVEEngagementStateEventStart: // A pop-up for purchasing items received through the IAPPurchase schema is displayed. break; case HIVEEngagementStateEventEnd: // Whether or not the purchase of the requested item was successful is communicated through the IAPPurchase schema. if(![result isSuccess]) { return; } HIVEIAPV4Receipt * receipt = [param objectForKey: @ "iapV4Receipt"]; break; } break; case HIVEEngagementEventTypeSocialMyInquiry: switch (engagementState) { case HIVEEngagementStateEventStart: // Start my inquiry page exposure request break; case HIVEEngagementStateEnd: // My inquiry page has been exposed (delivered after the My Inquiry window is closed) break; } break; case HIVEEngagementEventTypeSocialProfile: switch (engagementState) { case HIVEEngagementStateEventStart: // Initiate profile page exposure request break; case HIVEEngagementStateEnd: // Profile page exposure completed (delivered after closing the profile window) break; } break; } }]; |
Settings to Handle User Engagement Event
The Hive SDK is generally able to process incoming requests if the Hive login is complete. However, in case of the first execution, etc., even after the login, compensation payment etc. may not be possible if it is before the game server DB creation. Therefore, you need to inform Hive SDK about whether UE event handling is possible from the game..
- The default settings for event handling is
false. - If event handling is set as
true, existing queued events are processed immediately, and subsequent events are processed immediately. - If event handling is set as
false, incoming events are queued until the setting is converts totrue. - Setting it to
trueshould be called after the login , and Setting it tofalsehas no restriction on the time of the call. - (With Hive SDK v4.4.0 and later) All games using Hive SDK are required to implement this API to give CPI rewards.
- If a user enters the app through the invitation links or QR codes generated by User Acquisition, or through offerwall pages, the entry history transfer and reward payment request are performed depending on the changed state by calling this API.
- You must call the API at the point when the game can perform the function of the UE.
Use setEngagementReady() method in the Promotion class to set whether UE event is available to process or not. Followings are sample codes to set as true.
Unity®
API Reference: hive.Promotion.setEngagementReady
|
1 2 3 4 5 6 7 8 9 |
using hive; Boolean isReady = true; ResultAPI result = Promotion.setEngagementReady(isReady); if (result.isSuccess()) { // call successful } |
C++
API Reference: Promotion::setEngagementReady
|
1 2 3 4 5 6 7 8 9 10 11 |
#include <HIVE_SDK_Plugin/HIVE_CPP.h> using namespace std; using namespace hive; bool isReady = true; ResultAPI result = Promotion::setEngagementReady(isReady); if (result.isSuccess()) { // call successful } |
Kotlin
API Reference: Promotion.setEngagementReady
|
1 2 3 4 5 6 7 8 9 10 |
import com.hive.Promotion import com.hive.ResultAPI val isReady = true val result = Promotion.setEngagementReady(isReady) if (result.isSuccess) { // call successful } |
Java
API Reference: com.hive.Promotion.setEngagementReady
|
1 2 3 4 5 6 7 8 9 10 |
import com.hive.Promotion; import com.hive.ResultAPI; boolean isReady = true; ResultAPI result = Promotion.INSTANCE.setEngagementReady(isReady); if (result.isSuccess()) { // call successful } |
Swift
API Reference: PromotionInterface .setEngagementReady
|
1 2 3 4 5 6 7 8 9 |
import HIVEService let isReady = true let result = PromotionInterface.setEngagementReady(isReady) if (result.isSuccess()) { // call successful } |
Objective-C
API Reference: HIVEPromotion:setEngagementReady
|
1 2 3 4 5 6 7 8 9 |
#import <HIVEService/HIVEService-Swift.h> BOOL isReady = YES; HIVEResultAPI *result = [HIVEPromotion setEngagementReady: isReady]; if ([result isSuccess]) { // call successful } |
Result Code for Request to Redeem Coupon
If promo code errors or other problems exist while processing coupon event, UE module displays a popup in accordance with error code that Hive defines to notify the circumstances to users.
The host value of coupon scheme URL is always hive.
| Code | Description | Code | Description |
|---|---|---|---|
| 200 | Access to wrong parameter | 305 | Unique coupon expired the available count |
| 201 | Sent wrong hash value | 306 | Expired coupon |
| 202 | Exceeded the usage limit for the account | 307 | Lack of required data to distinguish new/existing user or Active User system error |
| 203 | The available count of coupon exceeded | 308 | Not the target of this event. For existing users only |
| 204 | Mismatched with AppID and issued coupon | 309 | Not the target of this event. For new users only |
| 300 | Coupon with wrong digit code | 310 | New/Existing event without registration in games |
| 301 | No coupon data in the promotion received | 400 | Failed to send all items |
| 302 | Failed to search the coupon code | 401 | Failed to send several items |
| 303 | Coupon in use | 500 | DB error |
| 304 | Used coupon | 501 | Communication failure |