Add a subscriber

There are multiple ways you can add subscribers to ReferralHero and generate a referral link, etc. Here we will walk through two ways of using our Javascript Web API to add a subscriber. You would want to use one of these functions if you want to use your own:

• Web signup form and add subscribers / identify them at the time of form submission

• Web login page and add subscribers / identify them at the time of form submission

Tip: You are adding a subscriber using our Javascript Web API and are taking advantage of our global tracking script and cookie!

This means the default referral link does not need to "point to" and/or potential subscribers do not need to "land on" the specific page URL including the 'add a subscriber' function.

Our global tracking script will automatically cookie and track each user as they visit and browse your website. The visitor will then convert to an "active subscriber" when they pass through your form/page which contains our 'add a subscriber' function.

To get the most out of your ReferralHero web integration, it is recommended that you use one of the ReferralHero widgets or 'add a subscriber' Javascript API (as detailed below). Not only are these the easiest ways to complete your setup, but you will also see improved tracking and deeper analytics reporting.

The two Javascript Web API functions available to 'add subscribers' are:

Add a Subscriber (Organic, Pending, or Confirmed)

RH_MFxxxxxxxxxx.form.submit(uniqueIdentifier);

When using this function 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 according to the above logic call ReferralHero's RH_MFxxxxxxxxxx.form.submit() function and send the user information such as email address, name, etc.

var form = document.getElementById('form');
form.addEventListener("submit", function(e){

    var data = {
      name: form.querySelector('#name'),
      email: form.querySelector('#email'),
      phone_number: form.querySelector('#phone_number'),
      crypto_wallet_address: form.querySelector('#crypto_wallet_address'),
      extra_field: form.querySelector('#country'),
      terms: true // Terms and conditions. Mandatory if your campaign  requires the acceptance of T&C
    };
    
    if (RH_MFxxxxxxxxxx) {
      RH_MFxxxxxxxxxx.form.submit(data);
    }

})

IMPORTANT

• 'MFxxxxxxxxxx' must be replaced with your campaign UUID.

• '#email, '#phone_number', '#crypto_wallet_address' or '#other ID' that have been enabled as the campaign unique identifier is required and can’t be blank.

• If you are using the ReferralHero Blockchain integration you must also send the '#crypto_wallet_provider' (see below).

• The ReferralHero Dashboard, Signup, Floating Widget, or Javascript API RH_MFxxxxxxxxxxform.submit() can only be used once on a single webpage. Do not add them multiple times on the same webpage.

Example: Add a Subscriber (Custom Unique Identifier - Crypto Wallet Address)

RH_MFxxxxxxxxxx.form.submit(uniqueIdentifier);

To add a subscriber using their crypto wallet address (for example, if you want to use your own 'wallet connect' to add participants and track referrals, according to the logic outlined above) simply call ReferralHero's RH_MFxxxxxxxxxx.form.submit() function and send the user's wallet address and wallet provider information.

var form = document.getElementById('form');
form.addEventListener("submit", function(e){

    var data = {
      crypto_wallet_address: form.querySelector('#crypto_wallet_address'),
      crypto_wallet_provider: form.querySelector('#crypto_wallet_provider'),
    };
    
    if (RH_MFxxxxxxxxxx) {
      RH_MFxxxxxxxxxx.form.submit(data);
    }

})

IMPORTANT

If you are using the ReferralHero Blockchain integration you must also send the '#crypto_wallet_provider' in the following format:

1. metamask

2. phantom

3. coinbase

4. ledger

5. exodus

6. trezor

7. myetherwallet

8. jaxx

9. guarda

10. trustwallet

*If there are additional wallets you'd like us to add, please email [e-mail].

Example: Running Multiple Campaigns

As an example, let's say you're running a language learning marketplace and need to set up two distinct campaigns for students and teachers/partners, while still having both user groups follow the same onboarding process, you can use the following approach. This setup allows you to determine which campaign organic subscribers should be added to, and ReferralHero will automatically identify which campaign referrals belong to.

1. Install the ReferralHero Global Tracking Script in the <header> of your website.

2. Decide which campaign organic subscribers should be added to by defining the UUID in the function.

3. Call the RH_MFxxxxxxxxxx.form.submit() function and either an organic subscriber will be created in the campaign defined or a referral will be automatically identified and placed in the appropriate campaign.

Add a Pending Referral

RH.pendingReferral(uniqueIdentifier);

You would want to use this function if you want to track referrals entering the 1st step of your multi-step conversion event funnel.

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.

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

<script>
  window.RHConfig = {
    callbacks: {
      ready: function() {
            var data = {
              name: 'Dev Test',
              email: '[e-mail]'
            };
            if (RH) {
              RH.pendingReferral(data);
            }
      }
    }
  }
</script>

IMPORTANT

• '#email, '#phone_number', '#crypto_wallet_address' or '#other ID' that have been enabled as the campaign unique identifier is required and can’t be blank.

• The ReferralHero Dashboard, Signup, Floating Widget, or Javascript API can only be used once on a single webpage. Do not add them multiple times on the same webpage.

Sharing screen

After you submit the data to ReferralHero you probably want to give people their referral link and display other useful information. Below we explain the different options you have.

ReferralHero Sharing screen in a popup

If you have selected Open sharing screen in popup in your campaign settings (which is the default option), then the default sharing screen will automatically pop up. This option is perfect for those who want to use their own sign-up form but don't to spend too much time on the customization and are happy to use ReferralHero's default sharing screen.

ReferralHero Sharing screen inline

If you want to display the sharing screen inline, you must add a <div> to your page where you want the sharing screen to appear and give ReferralHero the ID of such div in the Configuration file.

<script type="text/javascript">
  window.RHConfig = {
    defaults: {
      sharing_screen_container_id: "referralhero-sharing" // The ID of the HTML container
    }
  }
</script>

<div id="referralhero-sharing"></div>

Custom sharing screen

Alternatively, you can decide to create your own sharing screen and customize the whole experience. Be aware that this approach will take considerably longer to implement (although it will give you greater flexibility).

To create your own sharing screen you must use the Success callback in the Configuration File to override the default behaviour (which is to display the sharing screen).

<script type="text/javascript">
  window.RHConfig = {
    callbacks: {
      success: function(output) {
        // Your custom logic
      }
    }
  }
</script>

<!-- start ReferralHero tracking code -->
  <script type="text/javascript"> ...</script>
<!-- end ReferralHero tracking code -->

The success callback receives a parameter, which is an object with two properties: response and data.

Response can have the following values:

• subscriber_created when a new subscriber is created

• subscriber_retrieved when an existing subscribers is retrieved

• subscriber_not_verified when an existing subscriber who has not verified their email address is retrieved

• subscriber_not_found when no subscribers are found

• email_not_valid when the email submitted is not valid

• error if there's has been an error

Data ian object containing the subscriber's data (unless response is "error").

You can then use the subscriber's data (especially the "referral_link") to create your custom UI; for example, you can display a button to share on Twitter with a pre-composed tweet or store that information into your own database to send an email later.

You can see a working example here: https://codepen.io/Manu66/pen/vYYozLG