Pre-populating Users' Unique Referral Codes In Signup Flows & Forms

A how-to guide for ensuring a user's unique referral code is pre-populated in your signup flow or form when they share their unique referral link.

Background

The most frictionless way for a user to share a referral code is when they share a link to your signup flow or form that pre-fills their unique referral code in your signup flow's referral code field. You're able to configure this with Village's referrals setup.

Configuration with HTML form

1. Go to Side Menu > Referrals > Create New Referral

2. Mark 'Create a unique link and code for users'

3. You'll see this input:

Configuring the referral code

3. When creating the referral program, point 'https://your-url.com/signup/' to your domain's signup specific landing page. This will ensure that the referral link that is shared by a user will point at your landing page.

4. If you want the user's code to be pre-filled in the referral code field in your signup form, you will generally have to modify the code of your web page and use a server-side or client-side programming language, like JavaScript, to parse the URL and fill in the referral code field automatically when the page loads.

5. Structure your URL such that the referral code can be passed as a query parameter, eg: https://your-url.com/signup/?referral_code={your_code}.

6. Ensure your referral code field in the signup form has a unique ID so that it can be selected using JavaScript. For example:

<input type="text" id="referralCode" name="referral_code" />

7. Parse the URL and set the value of the referral code field. Use JavaScript to parse the URL and pre-fill the referral code field when the page loads. Eg. add this script to your web page:

<script>
document.addEventListener('DOMContentLoaded', function() {
    // Parse the URL
    const urlParams = new URLSearchParams(window.location.search);
    // Get the referral code from URL parameters
    const referralCode = urlParams.get('referral_code');

    // If a referral code is present, set the value of the referral code field
    if(referralCode) {
        document.getElementById('referralCode').value = referralCode;
    }
});
</script>

8. Back in Village, input the URL you created in step 5. above into the unique link field when creating a new referral structure in Village:

Expected Workflow:

1. User goes to the URL when a referral code generated in Village is shared. Eg. https://your-url.com/signup/?referral_code={your_code}. The 'your_code' part is generated as a unique code for each user in Village.

2. The JavaScript code reads the referral_code parameter from the URL.

3. If a referral code is found, it sets the value of the referral code input field with the ID referralCode to the read referral code.

Configuration with Google Form

Pre-populating a referral code in a Google Form field is relatively straightforward.

1. Go to Side Menu > Referrals > Create New Referral

2. Mark 'Create a unique link and code for users'

Configuring the referral code

3. Go to the Google Form where you want to pre-propulate the referral code when shared. Make sure you have a 'Referral Code' field created in the form.

4. Click on the three vertical dots in the top right corner of the form. Select “Get pre-filled link.”

5. Fill out the form with the values you want to be pre-filled. In this case, write something like 'prefilled_value' into the 'Referral Code' field and leave the other fields blank.

6. Click on “Get Link” at the bottom right.

7. Copy the provided URL; this is your pre-filled form link.

8. The URL you copied will look something like this:

https://docs.google.com/forms/d/e/[FORM_ID]/viewform?usp=pp_url&entry.[FIELD_ID]=prefilled_value

9. Back within Village, replace 'https://your-url.com/signup/' in the unique link input field with the link you copied, replacing 'prefilled_value' with '{your_code}'. It should look something like: 'https://docs.google.com/forms/d/e/[FORM_ID]/viewform?usp=pp_url&entry.[FIELD_ID]={your_code}'

10. Create and test the link. If it is working successfully, when you enter the link, it should direct to your form with '{your_code}' prefilled in the Referral Code field.

11. When a user copies and shares their referral code link on their dashboard generated with this referral program, it will direct those they share it with to your Google Form signup with their unique code prefilled. Make sure you test this.