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

referral_code_param
optional
string

Use an alternative parameter for the referral code, instead of ref

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 succesfully 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 alway_callback: true in the options to make the callback always fire. In this case the callback will look as follows: function(error, result) { }

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 callls 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 usefulnes 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.

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).

attribution_id
optional
string

Attribution ids are used for lifetime commissions.

Lifetime commissions are subject to plan availability.

attribution_id_lifetime
optional
number

TTL in minutes for the attribution. Leave empty for indefinite.

program_group
optional
string

The id of the prohram 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 succesful 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).

attribution_id
optional
string

Attribution ids are used for lifetime commissions.

Lifetime commissions are subject to plan availability.

attribution_id_lifetime
optional
number

TTL in minutes for the attribution. Leave empty for indefinite

program_group
optional
string

The id of the prohram 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 succesful 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 alway_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 explicitely 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 succesful clicks

For now you can pass alway_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 asign 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>