Integration Scripts (JavaScript)

Referral Rock Integration Scripts are the easiest way to integrate your website with Referral Rock.  The primary function is to capture the new business on your own site so you can appropriately give credit and rewards to the members of your referral program. This article will explain:

  • What are Integration Scripts and how do they work
  • How to install Integration Scripts on your website
  • How to test and troubleshoot your Script setup
  • Adding conversion settings on the program level

What are Integration Scripts and how do they work?

The Integration Scripts are made up of JavaScript code snippets.

We currently offer two event scripts:

  1. Conversion Tracking
  2. Referral Update

The Conversion Tracking script is input on a page that signifies that a conversion, or sale, has happened.  This script allows you to create a Referral upon a sale or other desired action and add information (parameters) about your new referral from your own site. The most common place to use the Conversion Tracking script is on a purchase confirmation or thank you page within your e-commerce store.

Our Referral Update script is used when your sales process has more than one step and you need to move referrals between these steps. For instance, you might use the Referral Update script to: 

  • Move a Referral from the Pending to the Qualified status after signing up for a free trial
  • Move a Referral from the Qualified to the Approved status after they convert from a free trial to a paid user
  • Move a Referral from the Pending to the Approved status after they sign a contract

This allows you to automatically record where a Referral is in your process and update their status within Referral Rock accordingly.  Utilizing the referral statuses within Referral Rock is essential to mapping your sales process to the Referral lifecycle and generating rewards appropriately. Note that you do not need to use every referral status.  

How to install Integration Scripts on your website

Adding Integration Scripts to your website is a simple process. Follow the steps below to install your Integration Scripts on your site. 

Step 1: Install the Event Script

  1. Go to Integrations > Setup then select the Conversion Script or Referral Update Script
  2. Copy the code in the grey box and install on your website after the closing </body> tag. If you don't have direct access to the HTML on your platform, look for a setting to install '3rd-party tracking scripts', '3rd-party javascript', or 'custom javascript'.
  3. Configure the script to match the Referral Rock parameters (like name, email, etc.) to the merge tags or placeholder names in your service or platform. We have a lot of services pre-mapped in the External Service Integrations section, so check if your service or platform is there already to save some time. If you need help mapping parameters, please reach out to Referral Rock support. Be sure to include what service you are using and what parameters you want to map.
Avoid using a script manager such as Google Tag Manager for the Event Scripts, as it will not work with the variables used by most shopping carts and other website platforms.
The Referral Update Script requires at least one referralkey. This allows Referral Rock to identify which referral to update. You can only use a referralkey that is already associated with the referral. For instance, if you set a referral email with the conversion script, you can then use the referralkey_email parameter with the email placeholder from your service or platform in the update script to identify the referral.

Page-Load Triggering (Basic)

By default, the integration script will trigger a conversion or referral when the script is loaded with the page where it is placed. Simply placing the script on the page that signifies a conversion or update has taken place will ensure that your script will fire on page load. For example, placing the conversion script on a "Thank You" page after checkout ensures it will fire for everyone who has made a purchase on your website.

Manually Triggering (Advanced)

In addition to automatic triggering on page-load, the scripts are able to be triggered as and when needed directly using JavaScript. This is useful if you are using asynchronous page loading or require a conversion to occur after a button click or other on-page event. To manually trigger the scripts, we separate the script loading portion of the script and the event portion of the script. First, include the below function that loads the available Referral Rock scripts onto the page. Note that you will need to chance yoursite in the script to your unique Referral Rock subdomain.

(function (f, r, n, d, b, y) { b = f.createElement(r), y = f.getElementsByTagName(r)[0]; b.async = 1; b.src = n; b.id = 'RR_DIVID'; y.parentNode.insertBefore(b, y); })(document, 'script', '//yoursite.referralrock.com/webpixel/beta/universalv03.js');
          

Now, you're ready to call any of the available events. In this article, we'll cover the conversion script and update script, but also available is the access script for members and the widget script for putting an overlay referral widget on your site. You can call this function anywhere you would like, at which point the event will be triggered. The function takes the eventType as a string (conversion, referralupdate, access, widget) and an eventObject.

rrSpace.executeEvent(eventType, eventObject)

Be sure to set up your parameters in the eventObject so they are passed when the event is executed. 

The conversion event object is outlined below. 

rrSettingsConversion = {
            debug: "false",
            parameters: {
               fullname: "",
               email: "",
               externalidentifier: "",
               amount: ""
               //The above parameters are an example of a few of the many parameters available
          }

The referralupdate event object is outlined below:

rrSettingsReferralUpdate = {
             debug: "false",
             parameters: {
                referralkey_id: "",
                programidentifier: "",
                status: "",
                amount: ""
                //The above parameters are an example of a few of the many parameters available
          }
          
A full example of manually triggering the conversion event:
var conversionObject =
             rrSettingsConversion = {
                debug: "false",
                parameters: {
                   fullname: document.getElementById("name").value,
                   email: document.getElementById("email").value,
                   amount: document.getElementById("purchase-price").value
                   //The above parameters are an example of a few of the many parameters available
                  }
              }
              
          rrSpace.executeEvent('conversion', conversionObject)
The above is an example only to show how to execute an event with an event object. You must configure your parameters to reference your own software or system.

Testing your Integration Scripts

Once you have completed the integration scripts installation, we recommend you test them in order to ensure they are working correctly and you are pulling all the necessary Referral information.

The Event Log

The Event Log is a great place to make sure that referrals and their information is being captured properly. Using the Event Log, you can view a list of all the integration events that are associated with your Referral Rock account. When you select details, you are able to view all the data being passed by the integration scripts and confirm that the desired parameters are being passed correctly.

Troubleshooting

Using the Event Log, you can confirm you are tracking conversions properly. However, if you check out your Event log and notice it is missing or pulling incorrect data, you might be making one of these common mistakes:

What Is HappeningWhat Causes ItHow to Fix It
No events under 'List All' in the Event Log.Integration Script is not firing.Ensure the script is installed on the correct page. Ensure that your website allows the use of 3rd-party JavaScript. Ensure there are no JavaScript errors using the console in the developer menu of your browser (Chrome LinkFirefox Link).
Event Log is showing conversions but metadata is missing or incorrect.Metadata is not correctly mapped to parameters.Ensure your script does not contain any placeholder information (like firstname: "George", lastname: "Washington"). Ensure your parameters are using site specific placeholders/merge tags or JavaScript references to on-page information. Ensure your parameters are strings.
Event Log is showing: Info - No Tracking ID.User did not go through a referral link before conversion.This happens when the conversion script fires but the user does not have a Referral Rock cookie from a member on their browser. If you are testing conversion tracking, ensure that you click through a live member's referral link. This can also happen if users switch devices, as member cookies are device specific.

Conversion Settings for your Individual Program

Once you set up your Integration Scripts, it is set up for the whole site on the account level. However, if you are interested in running multiple programs with different conversion tracking logic, we allow you to add Conversion Settings on the program level. For instance, if you want Referrals to be automatically approved for one program and not the another or set an expiration date for the cookie, you can do so in Conversion Settings.

To access your Conversion settings, go to your Program > Edit Program > Additional Options and select Conversion Settings.


How did we do?