What is User Acquisition?
You can attract new users by having users share their Invite URL or QR Code on their SNS with the Invite Feature offered by Hive. Rewards are given to both the one who invited his or her friend and to the one who was invited when the invited user installs the game and meets certain condition (conditions and rewards can be set up at Hive Console), such as reaching a specific level.
The target of invitation is not limited to Hive users. A unique Invite URL and a QR Code are issued per user to identify the user that invited others.
If an iOS user participates via the Invite URL, the following notice page will be exposed to prevent loss of matching.
UA should provide users with easy-to-achieve goals and give proper compensation to enhance their interest and engagement.
Hive UA Features
- Issue and share the invitation URL/QR code of games
- Cost Per Install (CPI), which rewards both user and invited friend if the friend installed the game
- Cost Per Action (CPA), which rewards both user and invited friend if the friend achieved a mission while playing the game
UA Invitation Process
To reward, you need to implement Hive ITEM.
Registering User Acquisition Campaign
You can register UA campaign on Hive Console. Hive provides two types of campaign.
- Achievement campaign by count – If the invited friends achieve the campaign goal, both user and new friends get rewards
- Achievement campaign by mission – If the number of friends who completed missions meet the setting numbers, both user and new friends get rewards
For more information how to configure a campaign, see Hive Console Promotion.
Implementing User Acquisition
Implement invitations and campaign UI for UA in the game, and encourage users to install apps.
Receiving Campaign information and Invitation URL/QR Code
To receive invitation URL/QR code and campaign information, call getAppInvitationData() method in the Promotion class. You can create invitation page or campaign screen based on the information from Hive.
Followings are sample codes to request the URL/QR code and campaign information to Hive.
API Reference: hive.Promotion.getAppInvitationData
|
1 2 3 4 5 6 7 |
using hive; Promotion.getAppInvitationData((ResultAPI result, AppInvitationData appInvitationData) => { if (result.isSuccess()) { // call successful } }); |
API Reference: Promotion::getAppInvitationData
|
1 2 3 4 5 6 7 8 9 |
#include <HIVE_SDK_Plugin/HIVE_CPP.h> using namespace std; using namespace hive; Promotion::getAppInvitationData([=](ResultAPI result, AppInvitationData appInvitationData) { if (result.isSuccess()) { // call successful } }); |
API Reference: Promotion.getAppInvitationData
|
1 2 3 4 5 6 7 8 9 10 |
import com.hive.Promotion import com.hive.ResultAPI Promotion.getAppInvitationData(object : Promotion.AppInvitationDataListener { override fun onAppInvitationData(result: ResultAPI, appInvitationData: Promotion.AppInvitationData?) { if (result.isSuccess) { // call successful } } }) |
API Reference: com.hive.Promotion.getAppInvitationData
|
1 2 3 4 5 6 7 8 |
import com.hive.Promotion; import com.hive.ResultAPI; Promotion.INSTANCE.getAppInvitationData((result, appInvitationData) -> { if (result.isSuccess()) { // call successful } }); |
API Reference: PromotionInterface .getAppInvitationData
|
1 2 3 4 5 6 7 |
import HIVEService PromotionInterface.getAppInvitationData() { result, appInvitationData in if result.isSuccess() { // call successful } } |
API Reference: HIVEPromotion:getAppInvitationData
|
1 2 3 4 5 6 7 |
#import <HIVEService/HIVEService-Swift.h> [HIVEPromotion getAppInvitationData: ^(HIVEResultAPI *result, HIVEAppInvitationData *appInvitationData) { if ([result isSuccess]) { // call successful } }]; |
After calling getAppInvitationData() method, data is sent through AppInivitationData object.
The Composition of AppInvitationData Object
| Field Name | Description | Type |
| qrcode | QR Code image for invitation to the game (Save bitmap image as HEXA string type) |
String |
| inviteMessage | Invitation message to the game | String |
| inviteCommonLink | Invitation link to the game | String |
| inviteHivemsgLink | Invitation link to the game by Hive message | String |
| eachCampaignList | Campaign list to reward whenever campaigns are completed | AppInvitationCampaign list |
| stageCampaignList | Campaign list to reward when a user achieves the invitation goal | AppInvitationCampaignStage list |
Sharing Media Files by Social Media
Hive provides a sharing function by social media, unavailable with Receiving Campaign information and Invitation URL/QR Code. Use the showUAShare() method in the Promotion class provided by Hive SDK v4.11.7 with the following SNS.
- Kakao Talk
- LINE
- Facebook Messenger
With Hive SDK v4.11.2 and later but earlier than v4.11.7, the function is available by using shareText() and shareMedia() method in the PlatformHelper class.
 |
 |
Sharing media files are available only when the file is saved on user device. To share a URL, use text sharing function or download files from the URL. Followings are sample codes to implement file share by social media.
API Reference: hive .Promotion.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 |
using hive; // invitation message String inviteMessage = appInvitationData.inviteMessage; // invitation link String inviteCommonLink = appInvitationData.inviteCommonLink; Promotion.showUAShare(inviteMessage, inviteCommonLink, (ResultAPI result) => { if (result.isSuccess()) { // call successful } }); |
API Reference: Promotion ::showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
#include <HIVE_SDK_Plugin/HIVE_CPP.h> using namespace std; using namespace hive; // invitation message string inviteMessage = appInvitationData.inviteMessage.c_str(); // invitation link string inviteCommonLink = appInvitationData.inviteCommonLink.c_str(); Promotion::showUAShare(inviteMessage, inviteCommonLink, [=](ResultAPI const &result) { if (result.isSuccess()) { // call successful } }); |
API Reference: Promotion.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
import com.hive.Promotion import com.hive.ResultAPI // invitation message val invitationMessage = appInvitationData?.inviteMessage ?: "" // invitation link val inviteCommonLink = appInvitationData?.inviteCommonLink ?: "" Promotion.showUAShare(invitationMessage, inviteCommonLink, object: Promotion.PromotionShareListener{ override fun onPromotionShare(result: ResultAPI) { if (result.isSuccess) { // call successful } } }) |
API Reference: com .hive.Promotion.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
import com.hive.Promotion; import com.hive.ResultAPI; // invitation message String inviteMessage = appInvitationData.getInviteMessage(); // invitation link String inviteCommonLink = appInvitationData.getInviteCommonLink(); Promotion.INSTANCE.showUAShare(inviteMessage, inviteCommonLink, result -> { if (result.isSuccess()) { // call successful } }); |
API Reference: PromotionInterface.showUAShare
|
1 2 3 4 5 6 7 8 9 10 11 12 |
import HIVEService // invitation message let inviteMessage = appInvitationData.inviteMessage // invitation link let inviteCommonLink = appInvitationData.inviteCommonLink PromotionInterface.showUAShare(inviteMessage, inviteCommonLink) { result in if result.isSucces() { // call successful } } |
API Reference: HIVEPromotion ::showUAShare:inviteLink:handler:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
#import <HIVEService/HIVEService-Swift.h> // invitation message NSString *inviteMessage = appInvitationData.inviteMessage; // invitation link NSString *inviteCommonLink = appInvitationData.inviteCommonLink; [HIVEPromotion showUAShare: inviteMessage inviteLink: inviteCommonLink handler: ^(HIVEResultAPI *result) { if ([result isSuccess]) { // call successful } }]; |
Designing an Invitation Screen
Invitation screen is displayed for users to invite friends to the game. Utilize qrcode or inviteCommonLink from AppInvitationData object to design the invitation screen. You can implement a game invitation screen in a game using the qrcode or inviteCommonLink of AppInivitationData object that is passed as a result of the getAppInvitationData() method call. Invitation page has no limit, but the information below should be clearly stated.
- A campaign with description of the following; the goals that an invite must achieve, a description of the goal, the rewards of achieving that goal, the number of times the invitation has been completed, and the number of invitations needed to achieve the goal.
- An invitation with description of the following; a list of friends who can be invited and specify the method or procedure for sending actual invitations.
Campaigns and invitation may consist of different screens depending on the game plan, or may be composed together on the same screen.
- An example of initial screen with
inviteCommonLink
It is recommended to display the invitation URL as shown in the example screen above and design the UI in the game so that the user can copy the URL to the clipboard.
Designing a Campaign Screen
AppInvitationData class defines eachCampaignList and stageCampaignList variables. The data type of eachCampaignList variable is AppInvitationCampaign class, and that of stageCampaignList is AppInvitationCampaignState. Each of them contains campaign and campaign achievement information.
A campaign screen is composed by using the following information.
The composition of AppInvitationCampaign object
| No. | Field Name | Description | Type |
| 1 | title | Campaign title | String |
| 2 | description | Campaign description | String |
| 3 | imgUrl | Image URL of campaign icon | String |
| item | Rewards information (‘key’ and ‘value’ data type with JSON or HashMap format. ’key’ is diverse depending on the campaign settings) | Map<key, value> | |
| 4 | count | The number of achieving campaign | Integer |
| 5 | limit | Maximum number of campaign target | Integer |
| – | order | The order that a campaign is exposing | Integer |
| – | campaignId | Campaign ID (the unique campaign ID issued by Hive server) | Integer |
The composition of AppInvitationCampaignStage object
| No. | Field Name | Description | Type |
| 1 | title | Campaign title | String |
| 2 | description | Campaign description | String |
| 3 | imgUrl | Image URL of campaign icon | String |
| item | Rewards information (‘key’ and ‘value’ data type with JSON or HashMap format. ’key’ is diverse depending on the campaign settings) | Map<key, value> | |
| 4 | count | The number of achieving campaign | Integer |
| 5 | limit | Maximum number of campaign target | Integer |
| 6 | goalCount | Achievement information (The number of achieving all levels) | Integer |
| goalTotal | Achievement information (The required number of achieving all levels to get rewards) | Integer | |
| – | order | The order that a campaign is exposing | Integer |
| – | campaignId | Campaign ID (Unique campaign ID issued by Hive server) | Integer |
Checking UA Sender’s Information
Information of User Acquisition Sender is now available in the client API as well.
Install and run the app by clicking the UA link a new user received first, then implement the SDK initialization and the login. Next, call the setEngagementReady(true) method in the Promotion class. After that, you can confirm the UA sender’s information through the AppInvitationSenderInfo object by calling the getAppInvitationSenderInfo method.
Followings are sample codes to check UA sender’s information.
API Reference: Promotion .getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 |
using hive; Promotion.getAppInvitationSenderInfo((result, senderInfo) => { if (!result.isSuccess()) { return; } if (senderInfo != null && !string.IsNullOrEmpty(senderInfo.vid)) { // Successful call and check inviter information } }); |
API Reference: Promotion ::getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
#include <HIVE_SDK_Plugin/HIVE_CPP.h> using namespace std; using namespace hive; Promotion::getAppInvitationSenderInfo([this](ResultAPI result, AppInvitationSenderInfo senderInfo) { if (!result.isSuccess()) { return; } if (senderInfo != NULL && !senderInfo.vid.empty()) { // Successful call and check inviter information } }); |
API Reference: Promotion.getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
import com.hive.Promotion import com.hive.ResultAPI Promotion.getAppInvitationSenderInfo(object : Promotion.AppInvitationSenderInfoListener { override fun onAppInvitationSenderInfo(result: ResultAPI, appInvitationSenderInfo: Promotion.AppInvitationSenderInfo?) { if (!result.isSuccess) { return } if (appInvitationSenderInfo != null && appInvitationSenderInfo.senderVid.isNotEmpty()) { // Successful call and check inviter information } } }) |
API Reference: Promotion .INSTANCE.getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 |
import com.hive.Promotion; import com.hive.ResultAPI; Promotion.INSTANCE.getAppInvitationSenderInfo((result, appInvitationSenderInfo) -> { if (!result.isSuccess()) { return; } if (appInvitationSenderInfo != null && !(appInvitationSenderInfo.getSenderVid().isEmpty())) { // Successful call and check inviter information } }); |
API Reference: PromotionInterface .getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
import HIVEService PromotionInterface.getAppInvitationSenderInfo() { result, senderInfo in if !result.isSuccess() { return } if let senderInfo = senderInfo, let vid = senderInfo.vid, !vid.isEmpty { // Successful call and check inviter information } } |
API Reference: HIVEPromotion getAppInvitationSenderInfo
|
1 2 3 4 5 6 7 8 9 10 11 |
#import <HIVEService/HIVEService-Swift.h> [HIVEPromotion getAppInvitationSenderInfo: ^(HIVEResultAPI *result, HiveAppInvitationSenderInfo *senderInfo) { if (![result isSuccess]) { return; } if (senderInfo != nil && [senderInfo.vid length] > 0) { // Successful call and check inviter information } }]; |
The composition of AppInvitationSenderInfo objrct
| No. | Field Name | Description | Type |
| 1 | vid | Sender’s vid | String |
Notifying CPA Achievement
When an invited friend installs a game or you reach the goal of the campaign, the game must inform the Hive server of the CPA achievement in order to be rewarded. Be sure to complete the following works before giving rewards.
If both works are completed, call CPA Achievement Notice API when CPA is achieved.