Personalized In App Referrals
It helps app developers to identify and implement the right growth hack, within seconds & without any coding. We provide easy to integrate SDK's for various platforms that include Android & iOS.
AppVirality Android SDK supports from Android (API level 8) and higher.
Throughout the document, invitation sender will be called as "Referrer" and receiver will be called as "Friend".
This applies for Gradle based projects. Add the following dependency to your build.gradle file:
dependencies {
compile 'com.appvirality:AppviralityUI:1.1.27'
}(or)
Please download the SDK source to customise the UI.
AppVirality SDK source for Android Studio can be downloaded from here , this includes test App.
- Once you've registered with AppVirality.com and add a new app, you will be given an App key.
- Create a configuration file in the assets path of your project called appvirality.properties
Within this file, enter your AppVirality App key:
#Appvirality App Key
appvirality.appkey = 02e1r5e99b94f56t69f42a32a00d2e7ff
NOTE: Don't forget to replace the key "02e1r5e99b94f56t69f42a32a00d2e7ff" with your App Key.
Add the following lines to your AndroidManifest.xml within the
<manifest...>
<manifest..>
<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="19" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Optional permissions. GET_ACCOUNTS is used to pre-populate customer's email in form fields. -->
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<!-- Optional permissions. WRITE_EXTERNAL_STORAGE is used to improve the performance by storing campaign images. -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<application..>
</application>
</manifest>AppVirality Uses Google Install Referrer for attribution as a fallback, In addition to Device finger printing.
Add the following code block if you don't have INSTALL_REFERRER in your manifest file Application Tag.
<receiver android:name="com.appvirality.android.AppviralityInstallReferrerReceiver" android:exported="true">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>(or)
If you already have INSTALL_REFERRER broadcast receiver, use following code block in your onReceive method:
String referrer = intent.getStringExtra("referrer");
AppviralityAPI.setBroadcastReferrerString(context, referrer);(or)
NOTE: If you have multiple install receiver in your App, please go through the documentation here.
1) IMP: Before start using AppVirality features, initialize the AppVirality SDK by calling AppviralityAPI.init in onCreate() method of your application Splash Activity class.
(preferably in your Splash Activity or Main Activity, so that your campaigns will be ready in the background by the time your app gets loaded. This ensures smooth user experience). This method will initialize the process of getting campaigns from server asynchronously, without effecting the user experience.
AppviralityAPI.init(getApplicationContext());NOTE: For better user experience, please call this method in very first page i.e. before showing your app initial screen. This will not effect your app launch time since the initialization process takes place in background.
NOTE: For security reasons, you may want to update details such as user information & user conversion events(like signup/Transaction events) from backend server with the help of API. Userkey is required to perform such operations using API. You can obtain userkey with the help of init callback
Set user identity to recognize the user same as your backend system. Also, it is required to personalize the referral messages and welcome screen, which will be shown to new users upon app installation. (Friends shall be able to see the referrer's name and profile picture to increases conversion). We will also pass these user details through web-hooks to notify you on successful referral or conversion(install,signup or transaction..etc.)
AppviralityAPI.UserDetails.setInstance(getApplicationContext())
.setUserEmail("emailid")
.setUserName("name")
.setUseridInStore("storeId")
.setProfileImage("userProfileUrl")
.setCountry("Country")
.setState("State")
.setCity("City")
//.isExistingUser(false)
//.setPushRegID("User-Push-Registration-ID")
.Update(new AppviralityAPI.UpdateUserDetailsListner() {
@Override
public void onSuccess(boolean isSuccess) {
Log.i("AppViralitySDK","Update UserDetails Status : " + isSuccess);
}
});- setUserEmail — email of the user.
- setUserName — First Name of the user, required to personalize the referral messages.
- setUseridInStore — ID of the user in your App(helps to identify users on dashboard as you do in your app).
- setProfileImage — User profile picture URL, required to personalize the referral messages.
- isExistingUser — Set this as True, if you identify the user as existing user(this is useful if you don't want to reward existing users).
Set "isExistingUser" property only on first App launch i.e. only once. On subsequent launches please don't set this property. At any point of time if you set this property to "True" all the existing user rewards will be set to "Rejected" state and also stops reward on future events. Request to use this property carefully.
- setPushRegID — Unique id assigned to the device by your Push Notification Service. Providing this helps AppVirality in sending Push Notifications to Users. Please find the help to Configure Push Notifications using GCM.
NOTE: Please update user details before sending any conversion event. This will ensure that the correct user details will be used to send reward notification.Upon successful conversion, web-hook will get fired with the provide user details.
In-App referral growth hack can be launched in 4 different ways. You can use any / all of these 3 options to launch the growth hack.
Option 1 - Launch from custom button i.e from "Invite Friends" or "Refer & Earn" button on your App menu
You can use the following method if you want to show some label or message bar, only if there is any campaign available for the user."CampaignReadyListner" will get called irrespective of campaign availability but if campaign is not available the "onCampaignReady" shall receive "null". This is mainly useful when you want to have some control over the "Invite" or "Share" button visibility.
Use below code block in onCreate of your Activity, this will get the campaign details configured on AppVirality Dashboard.
AppviralityAPI.setCampaignHandler(this, AppviralityAPI.GH.Word_of_Mouth,
new AppviralityAPI.CampaignReadyListner() {
@Override
public void onCampaignReady(CampaignDetails campaignDetails) {
//campaignDetails will be null if there is no active campaigns.
if(campaignDetails != null) {
//Here you can set your custom button/label visibility
//findViewById(R.id.btnInviteFriend).setVisibility(View.VISIBLE);
//Get the user referralCode
String myReferralCode =campaignDetails.Shortcode;
// Now campaign details are ready, pass details to the handler
CampaignHandler.setCampaignDetails(campaignDetails);
}
}
});Launch the GrowthHack by calling the below code block on "btnInviteFriend" button click:
// Launch on btnInviteFriend click event
CampaignHandler.showGrowthHack(Home.this, CampaignHandler.getCampiagnDetails());Tip: Let the App users know about referral program by showing mini notification or some banner to achieve great results.
Option 2 - Launch the GrowthHack Screen directly by add the following line in custom button click event.
AppviralityUI.showGrowthHack(MainActivity.this, AppviralityUI.GH.Word_of_Mouth);NOTE: This method will check for growth hack campaigns and launches the selected growth hack by showing the loading spinner.
Now , Little clean up. Call AppviralityUI.onStop() in your Activity onStop() method. this is required if you are using AppviralityUI.showGrowthHack
@Override
protected void onPause() {
super.onPause();
AppviralityUI.onStop();
}You can launch the GrowthHack from Mini notification. Just add the following line in the activity in which you want to show the mini notification. You can configure the Mini notification style and message from your AppVirality Dashboard. You can control the visibility of this mini notification from dashboard.(i.e. By setting launch conditions like after how many app launches you want to show the notification or after how many days of first install you want to show the notification).
AppviralityUI.showLaunchBar(this, AppviralityUI.GH.Word_of_Mouth);You can launch the GrowthHack from popup dialog. You can configure the popup dialog message and style from AppVirality Dashboard and you need not update your app every time you make the modifications.
AppviralityUI.showLaunchPopup(this, AppviralityUI.GH.Word_of_Mouth);Now , Little clean up. Call AppviralityAPI.onStop() in your Activity onStop() method. this is required only if you are using "Option-3" or "Option-4".
@Override
protected void onStop() {
super.onStop();
AppviralityAPI.onStop();
}Registering Events are very important to reward your participants (Referrer/Friend) in case of a successful event. Also to calculate the LTV of participant (Referrer/Friend), Tip: Identify top influencer's and make most of their network.
Please add the following code block after successful Signup i.e. in your Singup button click eventAppviralityAPI.saveConversionEvent("Signup", null, null);(or)
If you want to show reward toast message on signup, you can send the signup conversion event as following:
AppviralityAPI.claimRewardOnSignUp(getApplicationContext(), new AppviralityAPI.RewardClaimed() {
@Override
public void OnResponse(boolean isRewarded, String message) {
if(isRewarded)
{
Toast.makeText(getApplicationContext(), "You will receive the reward shortly, please check your email.", Toast.LENGTH_LONG).show();
}
else
{
Toast.makeText(getApplicationContext(), "Sorry..! Reward is only for new users, But you can earn by referring your friends." , Toast.LENGTH_LONG).show();
}
}
});AppviralityAPI.saveConversionEvent("Transaction", String transactionValue, String transactionUnit, JSONObject extraInfo);NOTE: "extraInfo" is useful if you want to save OrderID or any other order related information.
Example:
JSONObject extraInfo = new JSONObject();
extraInfo.put("OrderID", "465");
extraInfo.put("Ordernote", "CashonDelivery");
AppviralityAPI.saveConversionEvent("Transaction", "40", "$", extraInfo);
AppviralityAPI.saveConversionEvent("YOUR-CUSTOM-EVENT-NAME", null, null);
Some example event that you want to track and reward users are:
"Finished_Level_5"
"Clicked_Reorder"
"Completed_Purchase"
You will receive call backs on successful conversion(i.e. on successful referral). please follow the integration steps given below to receive the Client-Side(In App) or Server-Side(Webhook) call backs.
This is required if you want to reward the users with in-store credits or Custom Reward.(AppVirality will only handle the coupon distribution and other than coupons, you need to handle the reward distribution).
Referrer/Friend Rewards and Conversion Notifications
Proguard Configuration: If you use proguard with your application, there are a set of rules that you will need to include to get AppVirality to work. AppVirality will not function correctly if proguard obfuscates its classes.
-keep class com.appvirality.** { *; }
-dontwarn com.appvirality.**Congratulations! You have successfully completed the "Personalized-Referral" GrowthHack integration process.
Sitback and watch AppVirality in action by creating the campaigns from AppVirality Dashboard.
How to Add Test Devices & Test Referral Program
Please have a look at our Wiki page
- Getting Started With AppVirality Android SDK Integration
- AppVirality API for referral Growth Hack
- How to Add Test Devices & Test Referral Program
- Using Custom Domain
- Init Callback | hasReferrer | getUserKey
- Using Referral Code & Referral Link
- [Optional] Exclude Premium Users
- [Optional] Dynamic Share Message
- [Optional] Remind Later Settings
- [Optional] To Whom and When to Show Growth Hack
- [Optional] Reward Notifications or Web-hook Configuration
- [Optional] Android Push Notification Configuration
- [Optional] Personalized Welcome Screen
- Referral Program on Apps having Login and Logout