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

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

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

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

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

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

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://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('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://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))))');

  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://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('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://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))))');

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

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

Specifying an alternate cookie domain

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