Skip to main content
AffiliateBase
Features Pricing Compare Help
Log in Start for free

Install the Affiliate Tracking Script

Add the stable AffiliateBase tracking script to your shared site layout, configure your account ID, and prepare Stripe checkout attribution.

Table of Contents

Open Setup step 4, save the checkout path that matches your site, then expand Add tracking → View developer steps. The code stays collapsed until you need it so the setup checklist can keep one clear action in view. Connect Stripe separately in Setup step 1 before verifying payment attribution.

<script
  async
  src="https://app.affiliatebase.io/track.js"
  data-account-id="YOUR_ACCOUNT_ID">
</script>

Replace YOUR_ACCOUNT_ID with your account ID.

Receive updates automatically

This URL receives approved, compatible tracking updates without changing your snippet. Keep your existing consent-manager rules: load the script only when permitted. Already-open pages keep the version they loaded until a subsequent page load.

If you previously installed a numbered CDN URL, replace that URL with https://app.affiliatebase.io/track.js. Keep your account ID and other attributes. Replace the existing tag rather than adding a second copy. If your site uses Content Security Policy, allow app.affiliatebase.io in both script-src and connect-src.

The script sends a small installation diagnostic containing its version and script source. This does not create a referral or sale. Set data-telemetry="false" to disable diagnostics. See the tracking reference for developers who need explicit version control.

This single script tag is the automatic-install path. It does not require a separate command-queue preloader. If advanced code calls affiliatebase(...) before the remote script loads, add the preloader before this tag and wait for affiliatebase('ready', ...) before using the result.

If your first-party journey spans multiple sites or apps, add their hostnames under Approved site or app hosts in Setup or Settings → Tracking domains. Enter one hostname per line without a scheme or path. The server supplies this approved list to the script, which refreshes it on page load and when the page regains focus. The standard tag does not require manually adding data-domains; optional data-domains hints can narrow approved hosts for a link but cannot authorize arbitrary hosts.

Attribution uses host-only cookies by default and account-scoped browser storage. Add data-cookie-domain only when sibling subdomains need to share a valid parent-domain cookie.

Continue the same referral across approved domains

When a referred visitor follows a link to another approved first-party host, the tracker automatically adds a short-lived encrypted ab_handoff capability. The destination redeems it to restore the same referral UUID, visitor session, and original referral expiry. It does not create a new referral or visitor session, and the reserved parameter is removed promptly.

The capability is bound to the account, source host, destination host, selected referral, and existing visitor-session proof. Do not create ab_handoff URLs yourself or use a bare account ID or public referral UUID to mint one. If a capability is invalid, expired, or the destination was removed from the approved list, the page receives no new attribution but navigation and checkout continue. Retrying a still-valid capability is safe and restores the same referral/session without creating another referral. Existing valid destination attribution and merchant-owned via, referral, coupon, and hash values are preserved.

This continuity applies to approved first-party hosts. Stripe-hosted and other third-party checkout pages still require the Stripe or server-side handoff described below.

Add Stripe Checkout Attribution

Most Stripe-hosted setups only need the script on the same published page as the Stripe checkout link or element.

Use this path if your site links to a Stripe Payment Link. Existing https://buy.stripe.com/... links can stay unchanged:

<a href="https://buy.stripe.com/your_payment_link">Buy now</a>

Buy Button or Pricing Table

Keep the Stripe element on the same page as the AffiliateBase script:

<stripe-buy-button buy-button-id="buy_btn_xxx" publishable-key="pk_live_xxx"></stripe-buy-button>

<stripe-pricing-table
  pricing-table-id="prctbl_xxx"
  publishable-key="pk_live_xxx"
></stripe-pricing-table>

Custom or Backend-created Checkout Sessions

If your server creates Checkout Sessions, submit the referral ID to your server first:

<form action="/checkout" method="post" data-affiliatebase data-affiliatebase-param-name="referral_id">
  <button type="submit">Start checkout</button>
</form>

Then set client_reference_id server-side when creating the Stripe Checkout Session. Mirror the same generated referral ID into affiliatebase_referral_id metadata where your Checkout mode supports it:

referral_id = params[:referral_id].presence
referral_metadata = { affiliatebase_referral_id: referral_id }.compact

checkout_params = {
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
  line_items: [{ price: "price_xxx", quantity: 1 }],
  mode: "subscription"
}
checkout_params[:client_reference_id] = referral_id if referral_id.present?
checkout_params[:metadata] = referral_metadata if referral_metadata.present?
if checkout_params[:mode] == "payment"
  checkout_params[:payment_intent_data] = { metadata: referral_metadata } if referral_metadata.present?
elsif checkout_params[:mode] == "subscription"
  checkout_params[:subscription_data] = { metadata: referral_metadata } if referral_metadata.present?
end

Do not use the public ?via token as client_reference_id. Stripe should receive the generated referral ID created by the tracking script.

Canonical Attribution Parameter

The tracking flow is built around ?via=TOKEN.

Example: https://yoursite.com/pricing?via=abc123

Key Runtime Values

  • window.AffiliateBase.referral
  • window.affiliatebase_referral

Browser state is only available in the visitor’s browser. Server-side Stripe code cannot read window.AffiliateBase unless the page submits the referral value first.

Checkout should remain usable if the tracker fails to load, is blocked, or times out. Continue without attribution when the current tracking attempt does not produce a referral; never block the purchase waiting indefinitely.

Identify a referred signup

To associate a signup email with the referral:

affiliatebase('identify', { email: 'customer@example.com' });

This records a lead, not revenue. Pass the generated referral ID to Stripe for purchase attribution; verified webhooks create the sale and commission. See the tracking reference for readiness and result handling.

Next steps