Getting Started

ReferralHero Kotlin / Java SDK

Getting Started

To start using the ReferralHero SDK, you will need to add it to your project as a dependency.

Step 1. Add the JitPack repository to your build.gradle file

Add it in your root build.gradle/setting.gradle at the end of repositories:

allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}

Step 2. Add the following to your build.gradle file:

dependencies {
        implementation 'com.github.maitre-app:ReferralHero-Android:$latest.release'
}

for KTS (1.0.6 as in Last Version available):

dependencies {
             implementation("com.github.maitre-app:ReferralHero-Android:1.0.6")
}

Step 3. Add Permission:

The ReferralHero SDK requires the following permissions. Add them to your AndroidManifest.xml file if they are not already present:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

If you are not targeting the Google Play Store, you need to add the following permission:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Step 4. Set up Proguard:

-keep class com.sdk.referral.** { *; }
-keep public class com.android.installreferrer.** { *; }

If you are not publishing your app in the Google Play Store, add the following com.sdk.rh rule:

-keep public class com.sdk.referral.** { *; }

Step 5. Set up install referrer intent:

If you are working with a store that supports the INSTALL_REFERRER intent, you can capture this with a broadcast receiver. Add the following receiver inside the application tag in your AndroidManifest.xml:

<receiver
            android:name="com.sdk.referral.receiver.RhReferrerReceiver"
            android:enabled="true"
            android:exported="true">
            <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER" />
            </intent-filter>
</receiver>

This receiver will retrieve the install referrer using below code in your file where you want to retrieve install referrer and register BroadcastReceiver in your main activity.

Java

public class MainActivity extends AppCompatActivity{
    private final BroadcastReceiver mUpdateReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            //put your logic here
       }
    };
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
     
    }
    @Override
    protected void onPause() {
     LocalBroadcastManager.getInstance(this).unregisterReceiver(mUpdateReceiver);
        super.onPause();
    }

    @Override
    protected void onResume() {
      LocalBroadcastManager.getInstance(this).registerReceiver(mUpdateReceiver, new IntentFilter(new RhReferrerReceiver().getACTION_UPDATE_DATA()));
        super.onResume();
    }
}

Kotlin

class MainActivity : AppCompatActivity() {
   private val mUpdateReceiver: BroadcastReceiver = object : BroadcastReceiver() {
       override fun onReceive(context: Context, intent: Intent) {
           //put your logic here
       }
   }

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
   }

   override fun onPause() {
       LocalBroadcastManager.getInstance(this).unregisterReceiver(mUpdateReceiver)
       super.onPause()
   }

   override fun onResume() {
       LocalBroadcastManager.getInstance(this).registerReceiver(
           mUpdateReceiver, IntentFilter(
               RhReferrerReceiver().ACTION_UPDATE_DATA
           )
       )
       super.onResume()
   }
}

If you are using a different broadcast receiver, you will need to set it up to communicate with the ReferralHero SDK. Follow these instructions to enable communication with the ReferralHero SDK broadcast receiver.

Multiple broadcast receivers

The ReferralHero SDK supports the INSTALL_REFERRER intent using a broadcast receiver. If several sources need to register a receiver, you will need to add your own BroadcastReceiver.

This receiver will call all the other receivers you want to support. Here is an example of a broadcast receiver:

<receiver
    android:name="com.your.app.InstallReceiver"
    android:permission="android.permission.INSTALL_PACKAGES"
    android:exported="true" >
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

If you are using your own broadcast receiver, you can pass the intent content to other receivers. Make sure to pass this information to the Adjust broadcast receiver and any others that need it:

Java

public class InstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Rh receiver.
        new RhReferrerReceiver().onReceive(context, intent);
      
    }
}

Kotlin

class InstallReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        // Rh receiver.
        context?.let { RhReferrerReceiver().onReceive(it, intent) }
    }
}

Step 6. Integrate the SDK into your App:

If you are integrating the Adjust SDK into a standard app, follow the Setup SDK steps below.

Setup SDK

We recommend using a global Android Application class to initialize the ReferralHero SDK. If you do not have this set up, follow these steps:

1. Create a class that extends the Application.

2. Open the AndroidManifest.xml file and locate the <application> element.

3. Add the android:name attribute and set it to the name of your application class. For example, if your Application class is named GlobalApplication:

<application
   android:name=".GlobalApplication"
   <!-- ... -->
 </application>

1. In your Application class, find or add the onCreate method. Add the following code to initialize the ReferralHero SDK:

Java

public class GlobalApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        RH.initRHSDK(this,"api_token", "Campaign_uuid");
    }
}

Kotlin

class GlobalApplication : Application() {
  
   override fun onCreate() {
       super.onCreate()
        val rh = RH.initRHSDK(this,"api_token", "Campaign_uuid")
        // or
        val rh = RH.initRHSDK(this, null, null) // if you defined the token on meta-data in AndroidManifest.xml
   }
}

You can find your ReferralHero API token and Tracking Code in your ReferralHero dashboard.

Get your API_TOKEN from the ReferralHero Dashboard -> API : https://app.referralhero.com/dashboard/apis

Back in the ReferralHero dashboard, click to edit your desired Campaign

Then the Installation tab, then Mobile App Installation

Get your UUID: The 12-letter id that starts with ‘MF’ in Edit Campaign > launch > Mobile app installation, e.g. MF15298bba6d

Now, the initRHSDK should look like this:

val rh = RH.initRHSDK(this,"MFcd4113d4bf", "0e5ee7b383a8103ac1c6a8ebac9e5736b3a4cead")
or
val rh = RH.initRHSDK(this, null, null)

This step is mandatory to Set up your ReferralHero API token and Tracking Code in your AndroidManifest.xml file. Without this ReferralHero SDK does not work properly or you can not use SDK Features.

You should add it to your app's AndroidManifest.xml. More about this can be found on ReferralHero dashboard > Campaign > Installation > Instructions.

Following the values we got for our campaign:

<meta-data
            android:name="com.sdk.referral.RhKey"
            android:value="0e5ee7b383a8103ac1c6a8ebac9e5736b3a4cead" />

 
 <meta-data
            android:name="com.sdk.referral.uuid"
            android:value="MFcd4113d4bf" />

1. In the Goal section of your Campaign settings, ensure you have added the Google Play and Apple App Store links and a default referral link for desktop web users.

Well done! You should now be able to build and run your campaign. Before using the more advanced features of the SDK, you should make sure you have reviewed the following important concepts:

• Getting Started

• Setup SDK

• Checkout Github Sample

There are a few major components in the SDK that you can include in your app check out Public Methods.

Tracking Referrals

Now that you have implemented the SDK, you can start identifying and tracking referrals!

For that, you will need 2 things:

1. Universal Link

2. Your Integrated App

The RH SDK Pulls information from your Device, like this:

var rh: RH? = RH.instance
val referralParams = ReferralParams()
referralParams.email = signup_email?.editText?.text.toString() //Capture this from user
referralParams.domain = "https://a.domain.co/" //Optional value, and set as default by admin
referralParams.name = Username?.editText?.text.toString() //Capture this from user
referralParams.referrer = referralcode?.editText?.text.toString().trim { it <= ' ' } //Optional value, only necessary if you want to capture the referrer code from user 
referralParams.uuid = "MFcd4113d4bf"//Get this from RH Dashboard
referralParams.device = rh?.deviceInfo?.getDeviceType()
referralParams.ip_address = rh?.deviceInfo?.getIpAddress()
referralParams.os_type = rh?.deviceInfo?.getOperatingSystem()
referralParams.screen_size = transformResolution(rh?.deviceInfo?.getDeviceScreenSize())
referralParams.status = "custom_event_pending"

The format for android screen sizes is not native to RH, and the format should be parsed to RH accepted, such as:

fun transformResolution(input: String?): String {
    val dimensions = input?.split('*')?.map { it.trim().toFloat()}
    return "${dimensions?.get(0)} x ${dimensions?.get(1)}"
}

With this information, you should be able to add the subscriber data, with the Get Referrer, Add Subscriber, Create Pending Referral, or Track Referral methods to automatically identify or track a referral:

fun formSubmit()
{
    RH.formSubmit(referralParams)
}

To further understand the implementation of these methods, please check the Public Methods section, and our Github Sample Project.