Tapfiliate.js docs

This page contains a full reference of the Tapfiliate javascript library. This documentation is meant to be used when implementing Tapfiliate's advanced features. For standard integrations, please refer to our integration guides.

To integrate the javascript snippet on your website please follow our javascript integration guide.

Reference

create

Use this method to initialize tapfiliate.js.

tap('create', account id, options, callback);

Arguments

Account id
required
number
Example: 1

Your account id.

Options
optional
object
Example: {}

Currently no options. This argument only functions as a stub for possible future options.

Callback
optional
function

Callback, to be called after the tracking code has been initialized. In case a visitor id exists for the current visitor, tap.vids will be populated at this point.

detect

This method will scan the url for tracking parameters and will track a click, only if the proper parameters exists, that is if the user came through an affiliate referral code. If the detect method finds correct tracking parameters, a cookie will be set and when the client then gets in touch with the conversion code snippet that cookie will get triggered again, and a conversion recorded.

In case no tracking parameters are present or the detect method is not called, no external calls to Tapfiliate will be made.

tap('detect', options, callback);

Arguments

Options
optional
object

Options for this method

Options

cookie_domain
optional
string

Explicitly define the domain to place the cookie on. Can be used when users land on subdomain A and later convert on subdomain B.

referral_code
optional
string

Use this to explicitly pass a specific referral code for this click.

referral_code_param
optional
string

Use an alternative query parameter for the referral code, instead of ref. For example if you would like your links to look like: https://.../?via=, pass via

always_callback
optional
boolean

Set to true to also make your callback fire on failed tracking attempts. More info

Callback
optional
function
Example: 1

Callback, to be called after a click is tracked.

Important: This callback will only fire upon successfully tracked clicks. We are aware this is against convention. However, we're keeping it in place in order to not cause any BC breaks. The method will be deprecated in the future in favour of a new method, that uses conventional callback behaviour

For now you can pass always_callback: true in the options to make the callback always fire. In this case the callback will look as follows: function(error, result) { }

customer

Use this method track a new customer. Customers are usually tracked when a visitor, referred by an affiliate signs up for a trial or fills out a lead form. Then at a later point, one or more conversions will be created for the customer, e.g. on each successive payment of this customer. Also see trial (SaaS / Subscription) and lead (Lead-gen).

This code can always safely be outputted on your thank you page. This code will only track a customer when the current visitor was brought in by one of your affiliates, within the specified cookie time. For visitors not brought in by an affiliate, no external calls will be made.

tap('customer', customer id, options, callback);

Arguments

Customer id
required
string
Example: USER1234

The id for this customer in your system. The customer id should be unique for each customer.

Options
optional
object

Options for this method

Options

meta_data
optional
object

Can be used to store additional data alongside a customer

The following limitations apply to meta data:

  • Maximum key length: 64
  • Maximum value length: 255
  • Maximum number of properties: 10
  • Illegal characters: " : { } ] \ ' / &

coupons
optional
string|array

A string coupon code or array of coupon codes associated with this customer.

Coupon codes take precedence over traffic driven through affiliate links. If none of the supplied coupons is associated with an affiliate, we will fall back to cookies (if any).

always_callback
optional
boolean

Set to true to also make your callback fire on failed tracking attempts. More info

Callback
optional
function

Important: This callback will only fire upon successful customer creations. We are aware this is against convention. However, we're keeping it in place in order to not cause any BC breaks. The customer method will be deprecated in the future in favour of a new method, that uses conventional callback behaviour

trial

This is an alias of the `customer` method. However, it will set the initial status of the customer to "trial". Recommended for SaaS and Subscription businesses. You can read more about customer statuses here.

tap('trial', customer id, options, callback);

lead

This is an alias of the `customer` method. However, it will set the initial status of the customer to "lead". Recommended for lead-generation businesses, or businesses with a long / offline sales funnel. You can read more about customer statuses here.

tap('lead', customer id, options, callback);

conversion

Use this method track a conversion

This code can always safely be outputted on your thank you page. This code will only track a conversion when the current visitor was brought in by one of your affiliates, within the specified cookie time. For visitors not brought in by an affiliate, no external calls will be made.

tap('conversion', external id, amount, options, commission type, callback);

Arguments

External id
optional
string
Example: ORD1234

A unique id for this conversion. This value will be showed alongside your conversion on our platform and can be used for cross-referencing purposes. Depending on your use-case, this would usually be an order id, user id, subscription id, payment id or hashed email address.

Next to its usefulness for cross-referencing, the External id is also used for de-duplication on our end. I.e. we will not track a second conversion for the same external id. This could happen for instance when someone refreshes your thank you page.

Amount
optional
float
Example: 10.50

The order amount for this conversion. This is the amount of which we will base the commission amount, according to your configured commission percentage

Options
optional
object

Options for this method

Options

meta_data
optional
object

Can be used to store additional data alongside a conversion, e.g. order information or a hashed email.

The following limitations apply to meta data:

  • Maximum key length: 64
  • Maximum value length: 255
  • Maximum number of properties: 10
  • Illegal characters: " : { } ] \ ' / &

Important: Do not store Personal Identifiable Information (PII) in meta data.

customer_id
optional
string

The id of the current customer.

If you have recurring / lifetime enabled in your program, and a customer exists for the passed customer id, the conversion will be attributed to the original referring affiliate of that customer. Else, a new customer will be created.

currency
optional
string

The three letter ISO currency code.

Override the program's default currency for this conversion by explicitly passing a currency code.

coupons
optional
string|array

A string coupon code or array of coupon codes associated with the order.

Coupon codes take precedence over traffic driven through affiliate links. If none of the supplied coupons is associated with an affiliate, we will fall back to cookies (if any).

program_group
optional
string

The id of the program group to use.

Program groups are used for multi-domain set-ups.

always_callback
optional
boolean

Set to true to also make your callback fire on failed tracking attempts. More info

Commission Type
optional
string
Example: my-commission-type

The identifier of the commission type to use.

Callback
optional
function

Important: This callback will only fire upon successful conversions. We are aware this is against convention. However, we're keeping it in place in order to not cause any BC breaks. The conversion method will be deprecated in the future in favour of a new method, that uses conventional callback behaviour

conversionMulti

This method can be used to track conversion that have multiple commissions.

Example: If you want to differentiate the commission percentage per category, you can group the orders line item by category and track a separate commission for each category. Each commission can specify its own commission type identifier.

tap('conversionMulti', external id, options, commissions, callback);

Arguments

External id
optional
string
Example: 1

Numeric id of the conversion to perform action with.

Options
optional
object

Options for this method

Options

meta_data
optional
object

Can be used to store additional data alongside a conversion, e.g. a lead's name or hashed email.

The following limitations apply to meta data:

  • Maximum key length: 64
  • Maximum value length: 255
  • Maximum number of properties: 10
  • Illegal characters: " : { } ] \ ' / &

coupons
optional
string|array

A string coupon code or array of coupon codes associated with the order.

Coupon codes take precedence over traffic driven through affiliate links. If none of the supplied coupons is associated with an affiliate, we will fall back to cookies (if any).

customer_id
optional
string

The id of the current customer.

If you have recurring / lifetime enabled in your program, and a customer exists for the passed customer id, the conversion will be attributed to the original referring affiliate of that customer. Else, a new customer will be created.

currency
optional
string

The three letter ISO currency code.

Override the program's default currency for this conversion by explicitly passing a currency code.

program_group
optional
string

The id of the program group to use

Program groups are used for multi-domain set-ups

always_callback
optional
boolean

Set to true to also make your callback fire on failed tracking attempts. More info

Commissions
optional
array <object>
Example: [{commission_type: 'my-commission-type', sub_amount: 50.50}]

An array of objects. One object for each commission.

Child arguments

sub_amount
optional
number

The partial order amount for this commission. This is the amount of which we will base the commission amount, according to your configured commission percentage

commission_type
optional
string
Example: my-commission-type

The identifier of the commission type to use.

Callback
optional
function

Important: This callback will only fire upon successful conversions. We are aware this is against convention. However, we're keeping it in place in order to not cause any BC breaks. The conversion method will be deprecated in the future in favour of a new method, that uses conventional callback behaviour

For now you can pass always_callback: true in the options to make the callback always fire. In this case the callback will look as follows: function(error, result) { }

click

Important: This method is only useful for very select use-cases. For all standard integrations, use detect

Use this method if you want to create a click based on explicitly supplied tracking parameters. This method is useful when you have a look up dictionary with affiliate tracking parameters vs. some other value. E.g. a lookup dictionary of affiliate referring domains.

tap('click', tracking parameters, options, callback);

Arguments

Tracking parameters
required
object
Example: {referral_code: 'johndoe'} or {asset_id: '1-abcdef', source_id: '2-cdefgh'}

An object containing a referral code or a combination of an asset id and a source id. These can be retrieved, through the REST API for instance

Options
optional
object

Options for this method

Options

always_callback
optional
boolean

Set to true to also make your callback fire on failed tracking attempts. More info

Callback
optional
function

Important: This callback will only fire on successful clicks

For now you can pass always_callback: true in the options to make the callback always fire. In this case the callback will look as follows: function(error, result) { }

Examples

Tracking a specific commission type

If you have added multiple commission types for your program, you can specify which commission type applies for the conversion you are tracking.

<script src="https://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('conversion', '((((UNIQUE CONVERSION ID))))', ((((CONVERSION AMOUNT)))), {}, (**'COMMISSION-TYPE-IDENTIFIER'**));
</script>
  • COMMISSION-TYPE-IDENTIFIER is the identifier that was added when the commission was created. Commissions are created per program, from the ‘commission structure’ option in the program settings.

Tracking multiple commissions

When you need to track multiple commissions for a single conversion, conversionMulti can be used. This is useful when the commission you give, varies per product or category for example.

The usual approach is to loop over the line items in your order to build up an array of commissions.

<script src="https://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))))');

  var myOrder = {}; // get from your server

  var commissions = myOrder.lineItems.map(function(lineItem) {
    return {
      sub_amount: lineItem.subTotal,
      commission_type: lineItem.product.sku
    };
  })

  tap('conversionMulti', '((((UNIQUE CONVERSION ID))))', {}, (**commissions**));
</script>
                    

Note: Be aware that tracking different commissions for different products/categories might imply creating separate ‘thank you’ pages per product/category, each with the specific version of the tracking code.

Tracking to a specific program group

If you want to use Tapfiliate with multiple sites, you will need to create a program group for each site you will integrate Tapfiliate into and assign your program to that group. Next, you will need to add the program group identifier to your tracking code:

<script src="https://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('conversion', '((((UNIQUE CONVERSION ID))))', ((((CONVERSION AMOUNT)))), {(**program_group: 'my-group'**)});
</script>

Adding Meta Data to a conversion

If you want to store additional data alongside a conversion, e.g. a lead’s name and email, you can do so by adding a meta object within the options object in the conversion code:

<script src="https://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))))');

  var metaData = {
      email: "chuck@norris.com",
      foo: "bar",
  };

  tap('conversion', '((((UNIQUE CONVERSION ID))))', ((((CONVERSION AMOUNT)))), {(**meta_data: metaData**)});
</script>

Useful when visitors land on a specific subdomain and later convert on a different subdomain. In this case the cookie is set on the initial subdomain and is thus not visible from the second subdomain, and thus tracking will be lost. This can be fixed by explicitly setting the cookie on your main domain.:

<script src="https://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', {(**cookie_domain: 'your-main-domain.com'**)});
</script>