Public Methods

ReferralHero Flutter/Dart SDK

The ReferralHero Flutter SDK provides a simple and efficient way to integrate referral and contest functionality into your Flutter application. The SDK offers a set of public methods to access data, execute various tasks, and interact with the ReferralHero API.

The main class for interaction is ReferralHeroFlutter. This class is designed as a singleton, ensuring that the SDK is ready to use throughout the application lifecycle. It is recommended to initialize the SDK on the very first screen of your app.

1. Add a Subscriber

This method is most commonly used to add an organic subscriber or create a referral (if identified) after a user successfully signs up or logs in to your app.

When using this method please take note of your Campaign Goal as our tracking logic will depend on if you are tracking a single or multi-step conversion event.

GOAL: One Conversion Event If you have your Campaign Goal set up to track one conversion event, the following tracking logic will take place:

  • If a referral, a referral will be automatically created and set to Confirmed in the correct campaign.

  • If not a referral, an organic subscriber will be created in the campaign UUID specified.

  • If the subscriber exists in our database, the subscriber will be 'identified'. Data is not overwritten. Additional data will be created.

GOAL: Two or Three Conversion Events If you have your Campaign Goal set up to track two or three conversion events, the following tracking logic will take place:

  • If a referral, a referral will be created and set to Pending in the correct campaign.

  • If not a referral, an organic subscriber will be created in the campaign UUID specified.

  • If the subscriber exists in our database, the subscriber will be 'identified'. Data is not overwritten.

To add a subscriber (for example, post a successful signup or login) call the function and send the params information such as email address and name. The minimum values you should send for the endpoint to work are the following:

final subscriber = { 
    "email": "johnDoe123@gmail.com", 
    "domain": "https://a.domain.co/", 
}

To identify and create a referral, you must also send either the setReferrer OR the required mobile params so that our matching algorithm can automatically identify a referral.

"os_type": "Android",
"device": "Android",
"ip_address": "123.156.219.010",
"screen_size": "432.0 x 960.0",

NOTE: The mobile parameters must be sent in the correct format for our system to automatically identify and create a referral. See the Getting Started section here.

The accepted Screen Size formats are:

"screen_size":"393*852"
"screen_size":"393 x 852"
"screen_size":"393x852"
"screen_size":"393.0 x 852.0"
// in case you need to hard code values

Request Body

Name
Type
Description

email*

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

name

String

The name of the subscriber

crypto_wallet_address*

String

The crypto wallet address. Required if it is the unique identifier for the campaign.

phone_number*

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

extra_field

String

The extra field value of the subscriber

extra_field_2

String

The extra field 2 value of the subscriber

referrer

String

The referral code or email of the referrer

lifetime_spend

Number

Lifetime spend of the subscriber

subscribe_page_url

String

Subscribe Page URL of the Subscriber

landing_page_url

String

Landing Page URL of the Subscriber

is_quick_add_referral

Boolean

Send True only if you want to add the referral as Quick Add Referral otherwise False

option_field_value

String

Option field value of the subscriber

other_identifier_value*

String

The other identifier value (Required if other identifier enabled as unique identifier)

double_optin

Boolean

Send True if you want to send verification method before adding otherwise False

points

Integer

Points of the subscriber

crypto_wallet_provider

String

The crypto wallet provider

screen_size

String

The screen size of device used by subscriber when the referral link was clicked

ip_address

String

The IP address used by subscriber when the referral link was clicked

device

String

The device used by subscriber when the referral link was clicked

os_type

String

The Type of Operating system used by subscriber when the referral link was clicked

source

String

The source of the subscriber.

domain

String

URL used to generate the referral link.

transaction_id

String

The unique ID of the transaction. Useful when tracking purchases.

conversion_category

String

The type of subscriber. Useful for creating reports or segmenting subscribers.

conversion_value

Number

The monetary conversion value of the subscriber

status

String

Use 'custom_event_pending' to set the referral status to pending

final subscriber = { 
    "email": "test24@gmail.com", //Required value, capture this from user
    "domain": "https://yourwebsite.com", //Required value, should match the default referral link set within your RH account
    "name": "Test User 24", //Optional but recommended, capture this from user
    "referrer": referrer_input?.text, //Optional value, only necessary if the user will provide the referrer code directly, otherwise the below 4 params are required 
    "ip_address": referralHeroService.deviceInfo.getIpAddress(), //Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
    "os_type": referralHeroService.deviceInfo.getOperatingSystem(), //Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
    "screen_size": referralHeroService.deviceInfo.getDeviceScreenSize(), //Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
    "device": referralHeroService.deviceInfo.getDeviceType(),  //Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params    
    "status": "custom_event_pending", //Use 'custom_event_pending' to set the referral status to pending
};

await referralHeroService.addSubscriber(subscriber);

2. Add Pending Referral

This method is most commonly used to create a referral entering the 1st step of your multi-step conversion event funnel (i.e. after a referred user successfully signs up for your app). If you want us to automatically add every user to your campaign and determine if the user is a referral or not, use the Add Subscriber method instead. This logic only checks for referrals:

Tracking Logic

GOAL: Two or Three Conversion Events

Your campaign Goal must be set up to track two or three conversion events, and then the following tracking logic will take place:

  • If a referral, a referral will be automatically created and set to Pending in the correct campaign.

  • If not a referral, no subscriber will be created.

Request Body

Name
Type
Description

email

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

phone_number

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

crypto_wallet_address

String

The crypto wallet address of the subscriber. Required if crypto wallet address is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value of the subscriber. Required if other identifier value is the unique identifier for the campaign.

final referralParams = {
  "email": "pending@example.com", //Required value, capture this from user
  "name": "Pending User", //Optional but recommended, capture this from user
  "referrer": "8f01d5db", // Optional value, only necessary if the user will provide the referrer code directly, otherwise the below 4 params are required
  "ip_address": referralHeroService.deviceInfo.getIpAddress(), // Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
  "os_type": referralHeroService.deviceInfo.getOperatingSystem(), // Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
  "screen_size": referralHeroService.deviceInfo.getDeviceScreenSize(), // Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
  "device": referralHeroService.deviceInfo.getDeviceType(),  // Required value, necessary if you want RH to automatically identify & create a referral without the user providing the setReferrer params
};

await referralHeroService.createPendingReferral(referralParams);

To add a pending referral, simply call ReferralHero's createPendingReferral function and send the referralParams data.

The minimum values for this endpoint to work:

final referralParams = {
  "email": signup_email?.text,
  "referrer": "M12345fc2",
};

OR:

final referralParams = {
  "email": signup_email?.text,
  "ip_address": referralHeroService.deviceInfo.getIpAddress(), 
  "os_type": referralHeroService.deviceInfo.getOperatingSystem(),
  "screen_size": referralHeroService.deviceInfo.getDeviceScreenSize(),
  "device": referralHeroService.deviceInfo.getDeviceType(),
};

NOTE: The mobile parameters must be sent in the correct format for our system to automatically identify and create a referral. See the Getting Started section here.

3. Track Referral

This method is used for tracking a referral conversion event (i.e. a purchase, but can be any conversion event).

Tracking Logic:

  • If a referral and pre-existing in the campaign as Pending

OR

  • If a referral and setReferrer or mobile params are provided, a referral is automatically created in the correct campaign and

The Referral Is Set To:

  • Confirmed (if tracking two conversion events)

  • Unconfirmed (if tracking three conversion events)

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 will return.

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.

Request Body

Name
Type
Description

email*

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

crypto_wallet_address*

String

The crypto wallet address. Required if crypto wallet address is the unique identifier for the campaign.

phone_number*

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value. Required if other identifier value is the unique identifier for the campaign.

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

final referralParams = {
  "email": signup_email?.text, //Required value, capture this from user
  "name": signup_name?.text, //Optional value but recommended, capture this from user
  "referrer": "M12345fc2", //Optional value, only required if the user does not exist in the campaign
  "ip_address": referralHeroService.deviceInfo.getIpAddress(), //Optional value, only required if the user does not exist in the campaign
  "os_type": referralHeroService.deviceInfo.getOperatingSystem(), //Optional value, only required if the user does not exist in the campaign
  "screen_size": referralHeroService.deviceInfo.getDeviceScreenSize(), //Optional value, only required if the user does not exist in the campaign
  "device": referralHeroService.deviceInfo.getDeviceType(),  //Optional value, only required if the user does not exist in the campaign
};

await referralHeroService.trackReferral(referral);

If the referral is pre-existing in the campaign, the minimum value for this endpoint to work:

final referralParams = {
  "email": signup_email?.text,  
};

If the referral is NOT pre-existing in the campaign (and you want to identify and create a referral), you must send either the setReferrer OR the required mobile parameters in the correct format so that our matching algorithm can automatically identify a referral. See the Getting Started section here.

4. Confirm Referral

Use this method when your Campaign Goal is set to track three conversion events and you want to confirm a referral when your third conversion event occurs (complete profile, upgrade to a paid plan, end of the trial, etc).

Tracking Logic:

  • If a referral and pre-existing in the campaign as Unconfirmed

The Referral Is Set To:

  • Confirmed (if tracking three conversion events)

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

Request Body

Name
Type
Description

email

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value of the subscriber. Required if other identifier value is the unique identifier for the campaign.

crypto_wallet_address

String

The crypto wallet address of the subscriber. Required if crypto wallet address is the unique identifier for the campaign.

phone_number

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

await referralHeroService.confirmReferral('subscriberId');

5. Organic Track Referral

If you would like to add an organic subscriber or a track referral on the conversion page to your referral campaign, you can use the following method. This method would most commonly be used if the user has not been previously added to your campaign and instead directly passes through a post-checkout/subscribe event.

Tracking Logic:

  • If a referral and pre-existing in the campaign as Pending

OR

  • If a referral and setReferrer or mobile params are provided, a referral is automatically created in the correct campaign and

The Referral Is Set To:

  • Confirmed (if tracking two conversion events)

  • Unconfirmed (if tracking three conversion events)

OR

  • If not a referral, an organic subscriber is created in the campaign UUID specified.

Request Body

Name
Type
Description

email

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

phone_number

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

crypto_wallet_address

String

The crypto wallet address of the subscriber. Required if crypto wallet address is the unique identifier for the campaign.

other_identifier_value

String

The other identifier value of the subscriber. Required if other identifier value is the unique identifier for the campaign.

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

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

final referralParams = {
  "email": signup_email?.text,
  "name": signup_name?.text,
};

await referralHeroService.organicTrackReferral(referralParams);

If the referral is NOT pre-existing in the campaign (and you want to identify and create a referral), you must send either the setReferrer OR the required mobile parameters in the correct format so that our matching algorithm can automatically identify a referral. See the Getting Started section here.

6. Update Subscriber Details

This method is used to update various user-related data like username, address, etc. Request parameters are the same as before in the Add a Subscriber API.

Required body parameters are noted below, otherwise, all other available subscriber attributes can be found above under 'Add a Subscriber'.

Request Body

Name
Type
Description

email*

String

The email of the subscriber. Required if email is the unique identifier for the campaign.

phone_number*

String

The phone number of the subscriber. Required if phone number is the unique identifier for the campaign.

crypto_wallet_address*

String

The crypto wallet address. Required if it is the unique identifier for the campaign.

other_identifier_value*

String

The other identifier value. Required if other identifier enabled as unique identifier.

final updates = {
  "email": "test102@gmail.com",
  "name": "Test name new",
  "os_type": "Ubuntu"
};

await referralHeroService.updateSubscriber('subscriberId', updates);

7. Get Subscriber Details

This method is used to get the details of a particular subscriber.

Request Parameters

Name
Type
Description

subscriber_id*

String

The ID of the subscriber.

final details = await referralHeroService.getSubscriberDetails('subscriberId');

8. Delete Subscriber

This method is used to Delete a Subscriber.

Request Parameters

Name
Type
Description

subscriber_id*

String

The ID of the subscriber.

await referralHeroService.deleteSubscriber('subscriberId');

9. Capture Share

This method is used with parameters like 'copy', 'sms', 'facebook', 'twitter', etc. to capture a Share Event.

Request Body

Name
Type
Description

social

facebook

To capture a 'facebook' share event.

social

twitter

To capture a 'twitter' share event.

social

linkedin

To capture a 'linkedin' share event.

social

email

To capture a 'email' share event.

social

telegram

To capture a 'telegram' share event.

social

sms

To capture a 'sms' share event.

social

copy

To capture a 'copy' share event.

social

reddit

To capture a 'reddit' share event.

social

facebook messenger

To capture a 'facebook messenger' share event.

social

whatsapp

To capture a 'whatsapp' share event.

social

line

To capture a 'line' share event.

social

pinterest

To capture a 'pinterest' share event.

await referralHeroService.captureShare('subscriberId', 'facebook');

10. Get My Referrals

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

Path Parameters

Name
Type
Description

subscriber-id*

String

Subscriber ID

final referrals = await referralHeroService.getMyReferrals('subscriberId');

11. Get Leaderboard

This method is used for retrieving the campaign leaderboard.

final leaderboard = await referralHeroService.getLeaderboard();

12. Get Referrer

This method is used to retrieve the referrer of a user. By calling this method, you would know if someone was a referral or not, and then could:

  • Apply a discount code automatically to the checkout process

  • Personalize text shown on a page

final query = {
  "email": signup_email?.text, //Optional value, capture this from user
  "name": signup_name?.text, //Optional value, capture this from user
  "ip_address": referralHeroService.deviceInfo.getIpAddress(), //Required value
  "os_type": referralHeroService.deviceInfo.getOperatingSystem(), //Required value
  "screen_size": referralHeroService.deviceInfo.getDeviceScreenSize(), //Required value
  "device": referralHeroService.deviceInfo.getDeviceType(), //Required value
};

final referrer = await referralHeroService.getReferrer(query);

NOTE:

The mobile parameters must be sent in the correct format for our system to automatically identify a referral. See the Getting Started section here.

13. Get Rewards

Use this method to Get Rewards unlocked by a specific subscriber.

Name
Type
Description

subscriber-id*

String

Subscriber ID

final rewards = await referralHeroService.getRewards('subscriberId');
PreviousGetting StartedNextReact Native

Last updated