Quick Start: JavaScript

Add referral tracking to any website — Shopify, Squarespace, custom builds, or anything with a checkout. No server-side code required.

Prerequisites

An Advocate Loop account (sign up here)
Access to edit your site’s HTML (directly or via a tag manager like Google Tag Manager)

Step 1: Add the tracking script

Add this script tag to every page on your site, ideally in the <head> or just before </body>. Replace the Brand ID with yours from the Advocate Loop dashboard (Settings → API Keys).

<script src="https://api-production.advocateloop.com/al.js?brand=YOUR-BRAND-UUID"></script>

Example:

<script src="https://api-production.advocateloop.com/al.js?brand=88d7ea67-e034-41fe-aa78-2b3b97f869fd"></script>

This script automatically detects referral codes in the URL (?ref=CODE) and stores them for attribution.

Using Google Tag Manager

If you use GTM, create a Custom HTML tag with the script above and set it to fire on All Pages. No additional configuration is needed — the brand ID is embedded in the script URL.

The widget lets visitors claim referral discounts and lets customers sign up as advocates. Add an empty div wherever you want the widget to appear:

<div data-al-widget></div>

That’s it. The tracking script (al.js) automatically detects this element and loads the full widget UI into it.

If your widget should only appear on certain pages (like a landing page or services page), just place the div on that page. You can also tell the widget which page it’s on using the data-al-path attribute:

<div data-al-widget data-al-path="/services"></div>

Step 3: Track conversions

After a customer completes a purchase, record the conversion. Add this to your thank-you or order confirmation page:

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function() {
    AdvocateLoop.trackConversion({
      order_id: 'ORD-12345',       // Your unique order ID
      order_value: 95.00,           // Order total after discounts
      customer_email: 'buyer@example.com'
    });
  });
</script>

The AdvocateLoopQueue pattern ensures the conversion is tracked even if your code runs before al.js finishes loading.

Dynamic order data

Most platforms provide order data on the thank-you page via template variables. Here are examples for common platforms:

Shopify:

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function() {
    AdvocateLoop.trackConversion({
      order_id: '{{ order.order_number }}',
      order_value: {{ order.total_price | money_without_currency }},
      customer_email: '{{ order.email }}'
    });
  });
</script>

Squarespace (via code injection on order confirmation):

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function() {
    AdvocateLoop.trackConversion({
      order_id: '{orderId}',
      order_value: {orderSubtotal},
      customer_email: '{customerEmailAddress}'
    });
  });
</script>

Conversion parameters

Parameter	Type	Required	Description
`order_id`	string	Yes	Unique order identifier (prevents duplicates)
`order_value`	number	Yes	Total order value after discounts
`customer_email`	string	Yes	Customer’s email address
`customer_name`	string	No	Customer’s name
`referral_code`	string	No	Override — usually detected automatically from stored cookie
`visitor_id`	string	No	Override — usually detected automatically

Step 4: Configure your referral program

In the Advocate Loop dashboard:

Go to Settings → Referral Program
Set your customer discount (e.g., 15% off or $10 off)
Set your advocate reward (e.g., $10 credit per referral)
Set your attribution window (how long referral links stay valid)

Step 5: Test it

Create a test advocate in the dashboard and note their referral code
Open an incognito window and visit your site with the referral link:
```
https://yoursite.com/?ref=V2AVMRDJ
```
Open the browser console — you should see [AdvocateLoop] log messages confirming the click was tracked
Complete a test purchase — check the dashboard for the conversion

About the queue pattern

The AdvocateLoopQueue pattern shown in Step 3 ensures the conversion is tracked even if your code runs before al.js finishes loading. Wrap any call to the AdvocateLoop global in a queue function and the call will execute as soon as the script is ready.

Applying discounts

Advocate Loop tracks referrals and attributes conversions, but applying the actual discount depends on your platform:

Shopify — Create a discount code matching the referral code, or use Shopify Scripts
Squarespace — Use promo codes in Commerce settings
Custom checkout — Apply the discount in your backend when a referral code is present

The AdvocateLoop.getVisitorData() method returns the stored referral code so your frontend can display it or pass it to your checkout:

window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
AdvocateLoopQueue.push(function() {
  var data = AdvocateLoop.getVisitorData();
  if (data.referralCode) {
    console.log('Referred by:', data.referralCode);
    // Auto-apply discount in your checkout
  }
});

Troubleshooting

Script not loading

Check the browser console for network errors
Verify the brand UUID in the script URL is correct
Ensure the script tag is on the page (check Elements tab)

Click not tracked

Visit your site with ?ref=TESTCODE and check the console for [AdvocateLoop] messages
Verify the referral code exists in your dashboard

Conversion not recording

Check the console for errors after trackConversion() runs
Verify order_id, order_value, and customer_email are all present
Confirm the thank-you page also has the al.js script tag