User Engagement (UE, Deep link)
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 SDK, 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 SDK to request rewards. (Request for CPI rewards)
- Ensure that Game Client implement
setEngagementReadyAPI and send the request when Hive SDK module is available to perform the function of UE to process CPI rewards and others.
How to indicate scheme URL on¶
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}
Note
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.,
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.
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¶
Be aware that available API is different depending on authentication version, v4 or v1.
| API | Implementation | Auth v4 | Auth v1 |
|---|---|---|---|
| authlogin auth/login | membership login (Guest -> Verified account) | X | O |
| socialinquiry social/inquiry | Access to 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 IAP v4) | O | O |
| iappurchase | Item purchase on spot banner (Hive SDK v4.5.0 and later with IAP v4) When implementing iappurchase, setEngagementReady() becomes false automatically. After purchase, you need to set setEngagementReady() as true | O | O |
| social/myinquiry | Access to My Inquiry page | O | O |
| social/profile | Access to profile page | O | O |
Hive SDK 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
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
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 API` and `getProductInfo API` before changing the state of `setEngagementReady` as true.
* As game executes the logic after purchase, it pauses engagement action (`setEngagementReady` becomes false automatically).
* After purchase is complete, change the state of `setEngagementReady` as 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
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.
//<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 UE. How to declaration and registration depends on the version of Hive SDK.
Note
- From Hive SDK v4.5.0 and later, global callback declaration and registration are done through the handler registration API of Promotion class.
- Engagement Handler format and enum values are changed from Hive SDK v4.5.0 and later.
You must register global callback using the handler registration API of Promotion class. Followings are sample codes.
API Reference: hive.Promotion.setEngagementListener
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 membership login page exposure request
break;
case EngagementEventState.END:
// 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;
}
});
#include "HivePromotion.h"
FHivePromotion::SetEngagementDelegate(FHivePromotionOnEngagementDelegate::CreateLambda([this](const FHiveResultAPI& Result, const EHiveEngagementEventType& EngagementEventType, const EHiveEngagementEventState& EngagementEventState, TSharedPtr<FJsonObject> Param) {
switch (EngagementEventType) {
case EHiveEngagementEventType::EVENT_TYPE:
switch (EngagementEventState) {
case EHiveEngagementEventState::BEGIN:
// All actions of Engagement are performed
break;
case EHiveEngagementEventState::FINISH:
// All actions of Engagement are completed
break;
}
break;
case EHiveEngagementEventType::AUTH_LOGIN_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Hive membership login page display request start
break;
case EHiveEngagementEventState::EVENT_END:
// Hive membership login execution completed (passed after login completion/window close execution)
break;
}
break;
case EHiveEngagementEventType::SOCIAL_INQUIRY_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 1:1 inquiry page exposure request starts
break;
case EHiveEngagementEventState::EVENT_END:
// 1:1 inquiry page exposure complete (After closing the 1:1 inquiry window)
break;
}
break;
case EHiveEngagementEventType::PROMOTION_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Promotion View exposure request starts
break;
case EHiveEngagementEventState::EVENT_END:
// Promotion View exposure complete (delivered after closing the Promotion window)
break;
}
break;
case EHiveEngagementEventType::COUPON:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Start coupon consumption request
break;
case EHiveEngagementEventState::EVENT_END:
// Complete coupon consumption request and send response
break;
}
break;
case EHiveEngagementEventType::OFFERWALL_VIEW:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Start requesting to display the offerwall page
break;
case EHiveEngagementEventState::EVENT_END:
// Complete displaying the offerwall page (delivered after the offerwall window is closed)
break;
}
break;
case EHiveEngagementEventType::EVENT:
// If the host is game, pass the Param result value (Key: "api", "param")
// TODO: Perform logic processing according to the api and param values
break;
case EHiveEngagementEventType::IAP_UPDATED:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
//Signal to receive the purchase information as it has changed
break;
case EHiveEngagementEventState::EVENT_END:
// The purchase history has changed, so signal to receive it
FString TypeValue;
if (Param.IsValid() && Param->TryGetStringField(TEXT("type"), TypeValue)) {
if (TypeValue == TEXT("subscription")) {
// TODO: Restore subscription products
} else {
// TODO: Restore consumable products
}
}
break;
}
break;
case EHiveEngagementEventType::IAP_PROMOTE:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Passing IAP Promote data existence
break;
case EHiveEngagementEventState::EVENT_END:
if (!Result.IsSuccess()) {
return;
}
// Since IAP Promote data exists, we receive marketPid through check Promote API
FHiveIAPV4::CheckPromotePurchase(FHiveIAPV4OnCheckPromotePurchaseDelegate::CreateLambda([=](const FHiveResultAPI& PromoteResult, const FString& MarketPid) {
if (!PromoteResult.IsSuccess()) {
return;
}
// TODO: Request to purchase an item with the MarketPid passed in
FString IapPayload = TEXT("");
FHiveIAPV4::Purchase(MarketPid, IapPayload, FHiveIAPV4OnPurchaseDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveIAPV4Receipt& Receipt) {
// TODO: Request receipt verification with the received Receipt
}));
}));
break;
}
break;
case EHiveEngagementEventType::IAP_PURCHASE:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Display the purchase popup for the item received with the IAPPurchase schema
break;
case EHiveEngagementEventState::EVENT_END:
// Whether the purchase of the requested item was successful is transmitted through the IAPPurchase schema
if (!Result.IsSuccess) {
return;
}
FString ReceiptValue;
if (Param.IsValid() && Param->TryGetStringField(TEXT("iapV4Receipt"), ReceiptValue)) {
// Send purchase receipt
// TODO: Verify receipt and process item payment리
}
break;
}
break;
case EHiveEngagementEventType::SOCIAL_MY_INQUIRY:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// 내 문의 페이지 노출 요청 시작
break;
case EHiveEngagementEventState::EVENT_END:
// 내 문의 페이지 노출 완료 (내 문의 창 닫은 이후 전달)
break;
}
break;
case EHiveEngagementEventType::SOCIAL_PROFILE:
switch (EngagementEventState) {
case EHiveEngagementEventState::EVENT_START:
// Start requesting display of my inquiry page
break;
case EHiveEngagementEventState::EVENT_END:
// Complete display of my inquiry page (sent after closing the My Inquiry window)
break;
}
break;
}
}));
API Reference: Promotion::setEngagementHandler
#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 membership login page exposure request
break;
case EngagementEventState::EVENT_END:
// 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;
}
});
API Reference: setEngagementListener
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 membership login page exposure request
}
Promotion.EngagementEventState.END -> {
// 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 -> {}
}
}
})
API Reference: com.hive.Promotion.setEngagementListener
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 membership login page exposure request
break;
case END:
// 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;
}
});
API Reference: setEngagementHandler(_:)
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 membership login page exposure request
case .eventEnd:
// 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)
}
}
}
API Reference: HIVEPromotion setEngagementHandler
#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 membership login page exposure request
break;
case HIVEEngagementStateEnd:
// 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 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.
Note
- Use
setAdditionalInfo()method in the Promotion class to send game data of current user before callingsetEngagementReady()method. The game information sent by the use of coupons or User Acquisition is available for game studio. - Depending on the version of Hive SDK, the class of
setEngagementReady()method differs.
Hive SDK v4.5.0 and later¶
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.
API Reference: hive.Promotion.setEngagementReady
API Reference: Promotion::setEngagementReady
API Reference: Promotion.setEngagementReady
API Reference: com.hive.Promotion.setEngagementReady
API Reference: PromotionInterface .setEngagementReady
API Reference: HIVEPromotion:setEngagementReady
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 |