JavaScript SDK

The AdvocateLoop script (al.js) gives you a small browser-side API for tracking conversions and reacting to widget activity. It’s loaded by the same script tag that powers the widget.

For server-side tracking with no browser, use the REST API instead.

Loading the SDK

The SDK becomes available once the script tag is on your page:

html

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

The same script also tracks referral visits and renders any widgets you’ve placed — see Install the Widget Script.

The queue pattern

Your code may run before al.js finishes loading. So that a call always runs, push it onto AdvocateLoopQueue instead of calling the global directly:

html

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function () {
    AdvocateLoop.trackConversion({ /* ... */ });
  });
</script>

Anything you push runs as soon as the SDK is ready — and immediately if it has already loaded.

AdvocateLoop.trackConversion(params)

Records a conversion. Call it on your thank-you / order-confirmation page after a purchase.

html

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function () {
    AdvocateLoop.trackConversion({
      order_id: 'ORD-12345',
      order_total: 108.00,
      tax: 8.00,
      shipping: 10.00,
      discount: 5.00,
      customer_email: 'buyer@example.com',
      items: [
        {
          name: 'Vitamin C Serum',
          quantity: 2,
          unit_price: 32.00,
          sku: 'VITC-30',
          category_path: ['Skincare', 'Serums'],
          image_url: 'https://yourstore.com/img/vitc.jpg'
        },
        { name: 'Gift Wrapping', quantity: 1, unit_price: 4.00 }
      ]
    });
  });
</script>

Parameter	Type	Required	Description
order_id	string	Yes	Unique order identifier
order_total	number	Yes	What the customer paid (items + tax + shipping − discounts)
tax	number	Yes	Total tax. Use 0 if not applicable
shipping	number	Yes	Total shipping. Use 0 if not applicable
discount	number	Yes	Total discount applied. Use 0 if no coupon
customer_email	string	Yes	Customer’s email address
customer_name	string	No	Customer’s name
items	array	No	Line items in the order. Fields below.

Each entry in items:

Field	Type	Required	Description
name	string	Yes	Item or service name
quantity	number	No	Units. Defaults to 1
unit_price	number	No	Price per unit. Or send line_total for the line’s total
sku	string	No	SKU, plan code, or service code
category_path	string[]	No	Ordered category path, top level first — e.g. ['Skincare', 'Serums']
image_url	string	No	Image URL for the item

For platform-specific examples (Shopify, Squarespace), see the JavaScript Quick Start.

AdvocateLoop.trackClaim(params)

Records an early claim — a referral and an optional cart — before checkout.

html

<script>
  window.AdvocateLoopQueue = window.AdvocateLoopQueue || [];
  AdvocateLoopQueue.push(function () {
    AdvocateLoop.trackClaim({
      referral_code: 'JOHN123',
      email: 'buyer@example.com',
      name: 'Jane Doe',
      items: [
        { name: 'Vitamin C Serum', quantity: 2, unit_price: 32.00, category_path: ['Skincare', 'Serums'] }
      ]
    });
  });
</script>

Parameter	Type	Required	Description
referral_code	string	No	The code being claimed. Falls back to the stored referral code when omitted.
email	string	No	Customer’s email
name	string	No	Customer’s name
phone	string	No	Customer’s phone
items	array	No	Cart line items — same fields as the conversion items array above

Provide email, or rely on a prior referral visit in this browser.

Returns a promise that resolves with the API response, or rejects on failure.

Clicks and refunds

• Clicks are tracked automatically when al.js loads on a page reached through a referral link — nothing to call. Await AdvocateLoop.ready to know when init has finished, and use getReferralCode() / getVisitorId() to read the stored values.
• Refunds are server-side — send them from your backend via the REST API with your API key.

Widget events

The SDK dispatches DOM events you can listen for, to hook your own code into widget activity:

javascript

document.addEventListener('advocateloop:claim', function (e) {
  // e.detail: { email, referralCode }
});

document.addEventListener('advocateloop:share', function (e) {
  // e.detail: { email, referralCode, shareUrl }
});

Event	Fires when	e.detail
advocateloop:claim	A visitor submits the claim form	{ email, referralCode }
advocateloop:share	A visitor signs up as an advocate	{ email, referralCode, shareUrl }

Related

• JavaScript Quick Start — get tracking working step by step
• Widgets — placing and configuring the widget
• REST API — server-side tracking