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 to ReferralHero at the time of form submission
- Web login page and add subscribers to ReferralHero 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.
The two Javascript Web API functions available to 'add subscribers' are:
Add a Subscriber
RH.form.submit(uniqueIdentifier);
Add a Pending Referral
RH.pendingReferral(uniqueIdentifier);
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.
RH.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: Single-Step Conversion Event
If you have your Campaign Goal set up as a signle-step event, the following tracking logic will take place:
- If a referral, a referral will be created and set to Confirmed.
- If not a referral, an organic subscriber will be created.
GOAL: Multi-Step Conversion Event
If you have your Campaign Goal set up as a multi-step event, the following tracking logic will take place:
- If a referral, a referral will be created and set to Pending.
- If not a referral, an organic subscriber will be created.
To add a subscriber according to the above logic call ReferralHero's
RH.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) {
RH.form.submit(data);
}
})
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.
- If you are using the ReferralHero Blockchain integration you must also send the '#crypto_wallet_provider' (see below).
- The ReferralHero Combo, Signup, Floating Widget, or Javascript API RHform.submit() can only be used once on a single webpage. Do not add them multiple times on the same webpage.
RH.pendingReferral(uniqueIdentifier);
You would want to use this function if you want to track referrals entering the 1st step of your multi-step event conversion funnel.
GOAL: Multi-Step Event
Your campaign Goal must be set up as a multi-step event, and then the following tracking logic will take place:
- If a referral, a referral will be created and set to Pending.
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: '[email protected]'
};
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 Combo, 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.
RH.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
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) {
RH.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 [email protected].
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.
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.
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>
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.
Last modified 1mo ago