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.

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();
    }
}

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:

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

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:

Create a class that extends the Application.
Open the AndroidManifest.xml file and locate the <application> element.
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>

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

public class GlobalApplication extends Application {

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

class GlobalApplication : Application() {
  
   override fun onCreate() {
       super.onCreate()
        RH.initRHSDK(this,"api_token", "Campaign_uuid")
   }
}

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 ReferralHero dashboard, you shoould enter your desired Campaign

click on Edit, so you can enter the Campaign

Then the Installation tab, then Mobile App Installation

Get your UUID: The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

Now, the initRHSDK should look like this:

RH.initRHSDK(this,"MFcd4113d4bf", 
   "0e5ee7b383a8103ac1c6a8ebac9e5736b3a4cead")

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 to 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.token"
            android:value="0e5ee7b383a8103ac1c6a8ebac9e5736b3a4cead" />

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

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: