All Categories ​>​ Setup and Design ​>​ Program Integrations ​>​ Referral Update (JavaScript)

Referral Update (JavaScript)

Updated 1 week ago by Chris Hiller

What is the Referral Update Script?

The Referral Update Script is used when your sales process has more than one step and you want to track referrals as they move through each steps. Just like the Conversion Tracking Script, the Referral Update Script fires on page load and should be placed on the page that signifies an update has occurred. The Referral Update Script is used to do one or more of the following: 

  • Update the status of a Referral to Qualified or Approved after they complete a new step in your process
  • Add additional information to an existing Referral record, as it becomes available

For example, the Referral Update Script could be used to do the following:

  • Update the status of an existing referral from pending to approved when they sign up for a paid subscription following a free trial
  • Set the amount when an existing referral upgrades their account

The Referral Update Script requires a referral key. The referral key is a parameter that tells Referral Rock which referral to update. For instance, if you set the referral's email address during initial conversion with the Conversion Tracking Script, you would then be able to use the referralkey_email parameter in the Referral Update Script.

The three referral keys are:
1. Email Address (referralkey_email) - the most common method, as email address is ubiquitous as a unique identifier in many online systems
2. External Identifier (referralkey_externalid) - an id that you set that uniquely identifies the user within your system (UUID, username, etc.)
3. Internal Identifier (referralkey_id) - a unique identifier that is created by Referral Rock during initial conversion.

How to setup the Referral Update Script on your website

  1. Go to Settings > Integrations then select Referral Update Script or click here.
  2. Copy the code in the grey box and paste it into the HTML of the update page right before the closing </body> tag. If you do not have access to the HTML on your platform, look for a setting or plugin to install '3rd-party tracking scripts', '3rd-party JavaScript', or 'custom JavaScript'.
  3. Configure the referral key and set any new parameters to the merge tags, placeholder names, or JavaScript variable values on your site. To update the status, add one of the following as the value of the status parameter, depending on the status that loading this page represents: "qualified", "approved", or "denied".
If your referral update event cannot be defined by a page load (for instance a form submission that does not redirect to a Thank You page), or your website architecture does not use distinct page loads (for instance a Single-Page Application), we offer advanced functionality to trigger the Referral Update Script using a JavaScript Function.

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 Integration Event Log

The Integration 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 Integration 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 Happening

What Causes It

How 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 Link & Firefox 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.

How did we do?