> ## Documentation Index
> Fetch the complete documentation index at: https://developers.tapfiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript tracking

> Track clicks, customers and conversions from your website with tapfiliate.js.

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.

<Note>
  Using a shop or billing platform? Check the [integrations in the help center](https://support.tapfiliate.com) first: most of them set this up for you.
</Note>

## Setup

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

```html theme={null}
<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.

```js theme={null}
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.

```js theme={null}
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](#callbacks). |

```js theme={null}
tap('detect', { cookie_domain: 'example.com' });
```

## conversion

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

```js theme={null}
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. |

```js theme={null}
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.

```js theme={null}
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. |

```js theme={null}
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.

```js theme={null}
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. |

```js theme={null}
tap('trial', 'USER1234');
```

## click

<Warning>
  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.
</Warning>

Records a click from tracking parameters you pass explicitly.

```js theme={null}
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:

```js theme={null}
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:

```js theme={null}
tap('conversion', 'ORD123', 49.99, { program_group: 'my-group' });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.