JavaScript tracking

tapfiliate.js detects visitors who come through affiliate links and reports their sign-ups and purchases. It only needs your account ID, which is public, so it is safe to use in the browser.

Using a shop or billing platform? Check the integrations in the help center first: most of them set this up for you.

Setup

Add the snippet to every page of your site, so a click is recorded wherever the visitor lands:

<script src="https://script.tapfiliate.com/tapfiliate.js" type="text/javascript" async></script>
<script type="text/javascript">
  (function(t,a,p){t.TapfiliateObject=a;t[a]=t[a]||function(){
  (t[a].q=t[a].q||[]).push(arguments)}})(window,'tap');

  tap('create', 'YOUR_ACCOUNT_ID');
  tap('detect');
</script>

Then call conversion, customer, trial or lead on the page where the sale or sign-up happens. Calls are queued, so they work before the script has loaded. These calls only reach Tapfiliate when the visitor came through an affiliate within the program’s cookie time. For everyone else nothing is sent, so the code can stay on the page for all visitors.

create

Initializes tapfiliate.js.

tap('create', accountId, options, callback);

Argument	Type	Description
`accountId`	string, required	Your account ID.
`options`	object	Reserved, pass `{}`.
`callback`	function	Called once the tracking code is initialized. If the visitor already has a visitor ID, `tap.vids` is filled at this point.

detect

Looks for affiliate tracking parameters in the URL. If it finds them, it records a click and sets a cookie, so a later conversion is attributed to the affiliate. Without tracking parameters it makes no request.

tap('detect', options, callback);

Option	Type	Description
`cookie_domain`	string	Domain to set the cookie on. Use your main domain when visitors land on one subdomain and convert on another.
`referral_code`	string	Referral code to use for this click instead of the one in the URL.
`referral_code_param`	string	Query parameter that carries the referral code instead of `ref`, for example `via` for links like `?via=janejameson`.
`always_callback`	boolean	Also call the callback when tracking fails. See callbacks.

tap('detect', { cookie_domain: 'example.com' });

conversion

Tracks a conversion, usually a purchase. Put it on your thank-you page.

tap('conversion', externalId, amount, options, commissionType, callback);

Argument	Type	Description
`externalId`	string	A unique ID for this conversion, such as your order ID. A second conversion with the same ID is not tracked, so reloading the thank-you page is safe.
`amount`	number	The order amount. Commissions are calculated from it.
`options`	object	See below.
`commissionType`	string	Identifier of the commission type to use, if your program has several.
`callback`	function	Called after the conversion is tracked.

Option	Type	Description
`customer_id`	string	Your ID of the customer. With recurring or lifetime commissions, the conversion goes to the affiliate who referred this customer. If the customer doesn’t exist yet, it is created.
`currency`	string	Three-letter ISO currency code, if it differs from the program currency.
`coupons`	string or array	Coupon codes used in the order. A coupon linked to an affiliate wins over the cookie.
`meta_data`	object	Extra data to store with the conversion. Up to 10 properties, keys up to 64 and values up to 255 characters, without `" : { } ] \ ' / &`. Do not store personal data.
`program_group`	string	Program group to track to, for setups with several sites.
`always_callback`	boolean	Also call the callback when tracking fails.

tap('conversion', 'ORD123', 49.99, {
  customer_id: 'USER1234',
  currency: 'EUR',
  meta_data: { plan: 'pro' },
});

conversionMulti

Tracks one conversion with several commissions, for example a different rate per product category.

tap('conversionMulti', externalId, options, commissions, callback);

options is the same as for conversion. commissions is an array with one object per commission:

Field	Type	Description
`sub_amount`	number	The part of the order amount for this commission.
`commission_type`	string	Identifier of the commission type.

var commissions = order.lineItems.map(function (item) {
  return { sub_amount: item.subtotal, commission_type: item.category };
});

tap('conversionMulti', 'ORD123', {}, commissions);

customer, trial and lead

Track a customer when a referred visitor signs up, before they pay. Conversions you track later for the same customer_id are attributed to the same affiliate.

tap('customer', customerId, options, callback);
tap('trial', customerId, options, callback);
tap('lead', customerId, options, callback);

trial and lead work like customer and set the customer’s initial status to trial or lead. Use trial for SaaS and subscriptions, lead for lead generation and long sales cycles.

Option	Type	Description
`coupons`	string or array	Coupon codes the customer used. A coupon linked to an affiliate wins over the cookie.
`meta_data`	object	Extra data to store with the customer, with the same limits as for conversions.
`always_callback`	boolean	Also call the callback when tracking fails.

tap('trial', 'USER1234');

click

For standard setups use detect. click is for rare cases where you know the affiliate from your own data, for example a list of referring domains.

Records a click from tracking parameters you pass explicitly.

tap('click', trackingParameters, options, callback);

trackingParameters holds either a referral code or an asset ID and source ID, for example { referral_code: 'janejameson' } or { asset_id: '1-abcdef', source_id: '2-cdefgh' }. The only option is always_callback.

Callbacks

By default the callbacks of detect, conversion, conversionMulti, customer and click fire only on success. Pass always_callback: true in the options to get every outcome, with the conventional signature:

tap('conversion', 'ORD123', 49.99, { always_callback: true }, null, function (error, result) {
  if (error) console.warn('Tapfiliate conversion was not tracked', error);
});

Several sites

To track one program across several sites, create a program group per site, assign the program to it and pass the group in the conversion:

tap('conversion', 'ORD123', 49.99, { program_group: 'my-group' });

Get started

Tracking

Automation

Recipes

AI

Setup

create

detect

conversion

conversionMulti

customer, trial and lead

click

Callbacks

Several sites

​Setup

​create

​detect

​conversion

​conversionMulti

​customer, trial and lead

​click

​Callbacks

​Several sites

Setup

create

detect

conversion

conversionMulti

customer, trial and lead

click

Callbacks

Several sites