Public Methods

ReferralHero Kotlin / Java SDK

ReferralHero provides a very simple and efficient approach for an application to communicate with our SDK.

A whole set of public methods exists within the SDK using which you can easily access most of the data, execute various SDK tasks, invoke from a large set of APIs, etc.

ReferralHero is the main SDK class and point of interface for an application to communicate with the SDK.

Most of the methods you will use will be from this class, so it's very important to instantiate it before actually starting to use it. Though it can be instantiated from any class, it is highly recommended to do so on the very first screen of your app, so that the SDK would be ready to use by the time your app transits to the main screen.

Use the following code to instantiate the RH class:

RH rh = RH.getInstance();

NOTE:

As RH class uses singleton format, you can use the same above code to retrieve its instance throughout your app.

Below is a full list of public methods provided by the ReferralHero SDK, you can check them out to know their use case, return type, and input parameters:

1. Add Subscriber

Setting/Updating the ReferralParams details is an important step. This is how ReferralHero would be aware of the identity of a business user as classified by your app.

Parameters

referralParams

RHSubscriber

Carrying the user data to be updated.

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution; else NULL

Step 1.

Create a ReferralParams class object and set the various user details to identify the user matching your back-end system.

ReferralParams referralParams = new ReferralParams();
referralParams.setEmail("user_email_here");
referralParams.setDomain("your_custom_domin_url");
referralParams.setName("user_name_here");
referralParams.setReferrer("referrer_code");
referralParams.setUuid("user_campaign_here");
referralParams.setDevice("Android");

See here for more parameters of ReferralParams Class.

To add a subscriber (for example, post a successful signup or login) call ReferralHero's rh.formSubmit() function and send the ReferralParams information such as email address and name.

Step 2.

Invoke rh.formSubmit(RHReferralCallBackListener callback, ReferralParams referralparams ) method of the RH class to Add Subscriber API calls, passing the ReferralParams object created in the previous step and an RHReferralCallBackListener instance.

It is advised that you INITIALIZE the SDK in the Application class, so that we may ensure a smooth user experience check out this SDK initialize steps.

Use the following code to add a subscriber:

RH rh =  RH.getInstance();
rh.formSubmit(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
}, referralParams);

2. Update Subscriber Details

This method is used to update various user related data like username, address, etc.

First create a ReferralParams class instance and set the user data you want to update using its setter methods, then pass that instance in this method.

Parameters

referralParams

ReferralParams

Carrying the user data to be updated.

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Follow this step (Add a Subscriber - previously described)

Step 2.

Call rh.updateSubscriber(RHReferralCallBackListener callback, ReferralParams referralparams ) method of the RH class to Add Subscriber API calls, passing the ReferralParams object created in the previous step and an RHReferralCallBackListener instance.

RH rh =  RH.getInstance();
rh.updateSubscriber(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
}, referralParams);

3. Get Subscriber Details

This method is used to retrieve Subscriber details.

Parameters

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Call rh.getSubscriber(RHReferralCallBackListener callback) method of the RH class to get Subscriber API calls, passing the RHReferralCallBackListener instance.

RH rh =  RH.getInstance();
rh.getSubscriber(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
});

4. Delete Subscriber

This method is used to Delete newly Created Subscriber.

Parameters

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Call rh.deleteSubscriber(RHReferralCallBackListener callback) method of the RH class to get Subscriber API calls, passing the RHReferralCallBackListener instance.

RH rh =  RH.getInstance();
rh.deleteSubscriber(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
});

5. Track Referral

This method is used for the track conversion event. It means it is used to convert Referral status from pending to unconfirmed/confirmed.

If the referrer is present in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status.

If the referrer is not present in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created.

Note:

  1. Your campaign must be set up as a custom event or a multi-step event otherwise, an error will return.

  2. If the referral is present in ReferralHero with pending status, a successful response custom_event_completed will return.

  3. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response custom_event_completed with the data of the new confirmed referral will return.

  4. If a referral exists but the referral status is not pending, the error custom event is already completed will return.

  5. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error referer is invalid or not present will return.

  6. If the referral status is unconfirmed or confirmed, the error custom event is already completed and will return.

  • uniqueIdentifier is a placeholder.

  • When tracking referrals on your App you should ALWAYS send the ACTUAL unique identifier (email, phone number, crypto wallet address, or other ID) of the user in referralParams class Object

Parameters

referralParams

ReferralParams

Carrying the user data to be updated.

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Call rh.trackReferral(RHReferralCallBackListener callback, ReferralParams referralparams ) method of the RH class to Add Subscriber API calls, passing the ReferralParams object created in the previous step and an RHReferralCallBackListener instance.

Use the following code to Track referral:

RH rh =  RH.getInstance();
rh.trackReferral(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
}, referralParams);

6. Capture Share

This method is used to send the Share event to the RH. It means If a user called this method with any params like facebook, messenger, etc. We capture this as the share in our system.

Parameters

referralParams

ReferralParams

Carrying the user data to be updated.

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Call rh.captureShare(RHReferralCallBackListener callback, ReferralParams referralparams ) method of the RH class to Add Subscriber API calls, passing the ReferralParams object created in the previous step and an RHReferralCallBackListener instance.

Use the following code to Capture Share referral:

RH rh =  RH.getInstance();
rh.captureShare(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
}, referralParams);

7. Get My Referrals

This method is used for retrieving all referrals of the specific subscriber.

Parameters

callback

RHMyReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Call rh.getMyReferrals(RHMyReferralCallBackListener callback) method of the RH class to get Subscriber API calls, passing the RHReferralCallBackListener instance.

Use the following code to Get My referral:

RH rh =  RH.getInstance();
rh.getMyReferrals(new RH.RHMyReferralCallBackListener() {
   @Override
   public void onMyReferralSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onMyReferralFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
});

8. Get Leaderboard

This method is used for retrieving the campaign leaderboard. It will get Camping which will be mentioned in AndroidManifest.xml file.

Parameters

callback

RHLeaderboardReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Call rh.getLeaderboard(RHLeaderboardReferralCallBackListener callback) method of the RH class to get Subscriber API calls, passing the RHLeaderboardReferralCallBackListener instance.

Use the following code to Get My referral:

rh.getLeaderboard(new RH.RHLeaderboardReferralCallBackListener() {
   @Override
   public void onLeaderboardReferralSuccessCallback(@Nullable String response) {
      
   }

   @Override
   public void onLeaderboardReferralFailureCallback(@Nullable String response) {

   }
});

9. Pending Referral

This method is used for creating the Referral with the Pending Status.

Parameters

referralParams

ReferralParams

Carrying the referral data.

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Create a ReferralParams class object and set the various user details to identify the user matching your back-end system.

ReferralParams referralParams = new ReferralParams();
referralParams.setEmail("user_email_here");
referralParams.setName("user_name_here");

To add a pending referral, simply call ReferralHero's rh.pendingReferral() function and send the ReferralParams information such as email address and name.

Step 2.

Invoke rh.pendingReferral(RHReferralCallBackListener callback, ReferralParams referralparams) method of the RH class to Add Subscriber API calls, passing the ReferralParams object created in the previous step and an RHReferralCallBackListener instance.

Use the following code for pending referral:

RH rh =  RH.getInstance();
rh.pendingReferral(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
}, referralParams);

10. Organic Track Referral

If you would like to track referrals or add organic subscribers on the conversion page to your referral campaign, you can use this method.

If the Referrer code is present with a uniqueidentifier, We create the Referral with the status unconfirmed/confirmed referral on the basis of the ‘Review Referral’ feature enabled/disabled.

If the Referrer code is not present but uniqueidentifier is present, We create the Organic Subscriber.

If the Referrer code is not present but a uniqueidentifier is present and we also have the Referral with the same uniqueidentifier in the campaign with pending status, We will convert the status from pending to unconfirmed/confirmed referral on the basis of the ‘Review Referral’ feature enabled/disabled.

Parameters

referralParams

ReferralParams

Carrying the referral data.

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Create a ReferralParams class object and set the various user details to identify the user matching your back-end system.

ReferralParams referralParams = new ReferralParams();
referralParams.setEmail("user_email_here");
referralParams.setName("user_name_here");

To add an organic referral track, simply call ReferralHero's rh.organicTrackReferral() function and send the ReferralParams information such as email address and name.

Step 2.

Invoke rh.organicTrackReferral(RHReferralCallBackListener callback, ReferralParams referralparams) method of the RH class to Add Subscriber API calls, passing the ReferralParams object created in the previous step and an RHReferralCallBackListener instance.

Use the following code for organic referral track:

RH rh =  RH.getInstance();
rh.organicTrackReferral(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
}, referralParams)

11. Confirm Referral

Confirm a referral. Useful when your campaign has enabled the "Manual confirmation" option and you want to confirm referrals when a specific event occurs.

Note: Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a subscriber_not_found error.

Parameters

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Invoke rh.confirmReferral(RHReferralCallBackListener callback) method of the RH class to Confirm Subscriber API calls, passing an RHReferralCallBackListener instance.

Use the following code for confirm referral:

RH rh =  RH.getInstance();
rh.confirmReferral(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String response) {
       //on success put your logic here
   }

   @Override
   public void onFailureCallback(@Nullable String response) {
     //on failure put your logic here
   }
});

12. Get Referrer

You can Get Referrer data from this api. It will pass ipAddress, screen size, os etc. parameters in the header so you don't need to pass manually.

Parameters

callback

RHReferralCallBackListener

Callback interface if you want to get the callback after API execution ; else NULL

Step 1.

Invoke rh.getReferrer(RHReferralCallBackListener callback) method of the RH class to get referrer Subscriber data API calls, passing an RHReferralCallBackListener instance.

Use the following code to get Referrer data

RH.getInstance().getReferrer(new RH.RHReferralCallBackListener() {
   @Override
   public void onSuccessCallback(@Nullable String apiResponse) {
      //success
   }

   @Override
   public void onFailureCallback(@Nullable String apiResponse) {
      // fail       
   }
});