Referral Update Method

Overview

This method updates a Referral based on an on-page referral update event and is placed on confirmation pages.

🚧

Prerequisites

• The website must have the Referral.js SDK installed to use this JavaScript method.
• Ensure referral updates are enabled in your referral update settings.

❗️

Referral must exist in Referral Rock

For a referral update to work, the referral must already be added to referral rock. (via Conversion, API, or any other means of adding a referral)

The Referral Update Method  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 Event, the Referral Update Method fires on page load and should be placed on the page that signifies an update has occurred. The Referral Update Method 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 Method 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.

Method Usage

The script below must be placed on the webpage following a successful conversion event. This ensures the conversion event occurred and prevents Referrals from being created in error.

Page Examples: purchase confirmation

<script type="text/javascript">
    window.referralJS = ((window.referralJS !== null && window.referralJS !== undefined) ? window.referralJS : {});
    window.referralJS.referralUpdate = {
        debug: "false", //displays a iframe on page for on-page debugging
        parameters: {
            referralkey_id: "",
            //CONDITIONALLY REQUIRED. Used to positively ID the referral you want to update
            //Valid values are in the following format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
            referralkey_externalid: "",
            //CONDITIONALLY REQUIRED. Used to positively ID the referral you want to update
            //If searching by externalId, the externalid must have been registered with RR during conversion.
            referralkey_email: "|*[email protected]*|",
            //CONDITIONALLY REQUIRED. Used to positively ID the referral you want to update
            //If searching by email, the referral must already be registered
            programIdentifier: "",
            //HIGHLY RECOMMENDED. Used to help exclusively identify referrals
            //Valid value is program ID found on program dashboard
            status: "",
            //HIGHLY RECOMMENDED. Used to update the referral status (most common update)
            //Valid value is qualified, approved, denied
            amount: "999",
            //HIGHLY RECOMMENDED. Used to update the purchase amount of a referral
            //Enter as a float with up to 2 decimal points without any currency symbols (ex $100.71 as 100.71)
            //Required for rewards based on a % of referral amount
            firstName: "|*DONALD*|",
            lastName: "|*DUCK*|",
            fullName: "|*DONALD*| |*DUCK*|",
            companyName: "|*DUCK DYNASTY*|",
            externalIdentifier: "",
            email: "|*[email protected]*|",
            phone: "|*111-111-1111*|",
            note: "|*DONALD NOTE*|",
            publicNote: "|*DONALD PUBLIC NOTE*|",
            preferredContact: "|*EMAIL*|",
            customFields: {
                // Currently can add up to three custom text fields, others will be ignored
                customText: {
                    "|*DONALD TEXT 1 NAME*|": "|*DONALD TEXT 1 VALUE*|",
                    "|*DONALD TEXT 2 NAME*|": "|*DONALD TEXT 2 VALUE*|",
                    "|*DONALD TEXT 3 NAME*|": "|*DONALD TEXT 4 VALUE*|"
                },
                // Currently can add up to two custom options, others will be ignored
                customOption: {
                    "|*DONALD OPTION 1 NAME*|": "|*DONALD OPTION 1 VALUE*|",
                    "|*DONALD OPTION 2 NAME*|": "|*DONALD OPTION 2 VALUE*|"
                }
            }
        }
    };
</script>

Basic and Key Parameters

Used to identify the referral you want to update. These options are listed in order of best practice first.

The ideal matching parameter is the 'referralkey_id' but using the 'referralkey_email' or 'referralkey_externalId' in addition to the 'programIdentifer' is a great second option.

Additional Parameters

If these values are not set, the referral will keep the existing value

Custom Parameters

Up to three custom text fields and two custom options can be added as parameters. Text fields are intended for text entry fields, and options are meant for dropdown selection fields. Any additional custom parameters added will be ignored.

FAQ & Debug Help

Use the Integration Event Log to make sure Referrals and their information is being captured properly.

The Event Log displays all the integration events associated with the program. These events include referral update events and will show when method is triggered.

Clicking the details icon for the event will show all of the data being passed by the script and confirm the desired parameters are being saved correctly.

There is also a debug setting on the script that can be set to true. When this is done, an iFrame will appear after the page loads as pictured here: