This guide walks you through connecting your website with Tapfiliate. This setup is for advertisers who want to track clicks, conversions, and customers via a custom code embedded into their website.

JavaScript integration advantages

Compatible with various website types - If your platform-based website does not have a direct integration with Tapfiliate, JavaScript integration can be your magic wand, allowing you to connect a CMS-based website to your Tapfiliate program.
Flexible event tagging - Whether you aim to track a conversion, a sign-up, or even a newsletter subscription, JavaScript integration lets you set the conversion trigger to almost any event.
Not necessary to do server-side installation - Most of the websites have an instance for the custom code installation, where you can put Tapfiliate’s JavaScript code. If you have a custom website, you can add the code directly to the website pages.
Capable of covering advanced tracking cases - JavaScript integration works great when you need to perform complex tracking scenarios, such as tracking multiple commission types, assigning recurring commissions, or setting up coupon tracking.

JavaScript integration prerequisites

Before you start the integration process, make sure you have:

A Tapfiliate account (with access to your Account ID)
A website that allows for adding custom tracking codes
Admin/developer access to your site’s codebase

Setting up the JavaScript integration

1. Add the click tracking code.

Copy the code below and add it to your website's Header section, or paste it to all website pages. If your website is CMS-based, you should locate the instance where the system allows hosting of custom code. Make sure to replace 'YOUR ACCOUNT ID' with your Tapfiliate Account ID so that we can match visitor activity to your Tapfiliate account.

(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', { integration: "javascript" });

tap('detect');

</script>

2. Add the conversion tracking code.

To inform Tapfiliate that a conversion took place on your website’s end, you must add the conversion code to the page where an order/target action is confirmed.

The most basic version of this snippet includes the essential parameters: an external ID and the conversion amount.

(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', { integration: "javascript" });

tap('conversion', 'Unique Conversion Id', Conversion Amount);

</script>

Make sure to pass the relevant data from the order details within the placeholders in the code (‘Unique Conversion Id’ and Conversion Amount) so that the conversion data is recorded along with the transaction.

Verify your integration

Before setting your program live, you have to verify your JavaScript integration. The best way to do that is to use a test affiliate’s link and initiate a test purchase.

In your Tapfiliate account, locate a test affiliate record in the Affiliates section > Click to expand details > Copy their referral link.
Follow the test affiliate’s referral link to your website. Once a page is loaded, you should see a click tracked in your Recent Activity Box (Dashboard).
Initiate a purchase of a free product on your website or make a test sale/subscription. When set up correctly, you should be able to see the conversion tracked in your Recent Activity Box (Dashboard).

Additional functionalities of JavaScript integrations

As we have highlighted in this article, JavaScript integration is highly powerful for handling advanced use cases.

Option 1. Tracking a customer (or a signup)

A customer is an event that represents lead creation, user account creation, or a purchase of your product or service. Customers are usually tracked when a visitor, referred by an affiliate, signs up for a trial or fills out a lead form. Later, one or more conversions will be created for the customer, e.g., for each successful payment.

If you’d only like to track the customer without attaching any conversions just yet, you can use the code below. Depending on your use case, you may replace the customer in the code with the alias that best suits your use case. You may choose from the following: customer, trial, or lead.

(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', { integration: "javascript" });

tap('customer', 'Customer Id');

</script>

Option 2. Tracking recurring or lifetime commissions

If you aim to track recurring/lifetime commissions in your program, you will need to send the Customer ID when you track a conversion. This way, our system will recognize the customer attribution and attach the recurring/lifetime commission to a customer record in your program. If the customer with the respective ID is not found, Tapfiliate will create a new customer record.

(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', { integration: "javascript" });

tap('conversion', 'Unique Conversion Id', Conversion amount, {customer_id: "Customer Id" });

</script>

Option 3. Tracking an alternative commission type (Extra commission)

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

(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>

The 'COMMISSION-TYPE-IDENTIFIER' is created and stored in your Tapfiliate account, under Programs > Commission structure > Extra commissions. Depending on the value passed in the parameter, the appropriate commission will be applied to the conversion.

Option 4. Tracking multiple commissions (conversionMulti method)

When you need to track multiple commissions for a single conversion, use conversionMulti. This is useful when the commission you offer varies by product or category.

Usually, you loop through the order’s line items to create the commission array.

(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>

Option 5. Attaching metadata to a conversion

Suppose you need to store additional information alongside a conversion (not collected in the default parameters), such as a name, subscription type, or product quantity. In that case, you can add the meta_data object with the options listed in the conversion code.

(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",

gender: "male",

};

tap('conversion', 'Unique Conversion Id', Conversion amount, {meta_data: metaData});

</script>

In this example, we fetch the user’s email address and gender as metadata, passed in the email and gender metadata keys.

Tapfiliate’s JavaScript library 📚

Below, we’ll go over these and list all available objects and methods you can use when integrating via JavaScript.

Method: create

This method is used to launch (initialize) the Tapfiliate JavaScript function on the website.

Method example:

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

Available arguments:

Account id (required) - Example: 1. Your Tapfiliate account ID, can be found in your Profile Settings.
Options (optional, can be left empty, as {}) - Currently, no options. This argument serves only as a placeholder for possible future options.
Callback (optional) - A function to be called after the tracking code has been initialized. If a visitor ID exists for the current visitor, a tap_vid cookie will be set at this point.

Method: detect

This method scans the URL for a referral code (or a combination of the tap_a and tap_s parameters) and tracks a click only if the user arrived via an affiliate referral link. Once a detect method locates the correct parameter, a Tapfiliate cookie will be set, and when the client then gets in touch with the conversion code snippet, that cookie will get triggered again and create a conversion record.

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

Method example:

tap('detect', options, callback);

Available arguments:

object
Options
Cookie_domain (optional) - A string that explicitly defines the domain to place the cookie on. Can be used when users land on subdomain abc.com and later convert on subdomain def.abc.com.
Referral_code (optional) - Use this string to pass a specific referral code for this click explicitly.
Referral_code_param (optional) - Use this string as 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) - Set this boolean argument to true to also make your callback fire on failed tracking attempts.
Callback (optional) - Passed as a function with a 1 or 0 value. This callback will only fire when a customer is successfully created.

Method: customer

Method example:

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

Available arguments:

Customer id (required) - Example: USER1234. The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. This ID must be unique for each customer.
Options

Meta_data (optional) - Metadata for this customer record, used if you need to attach additional information to customer details that is not listed within the existing parameters above.

The following limitations apply to metadata:

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

Coupons (optional) - A string coupon code or an array of coupon codes associated with this customer. Coupon codes take precedence over traffic driven through affiliate links. If none of the supplied coupons are related to an affiliate, we will fall back to cookies (if any).
always_callback (optional) - A boolean value; set to true to also make your callback fire on failed tracking attempts.
Callback (optional). Important: This callback will only fire when a customer is successfully created.

You can place this code on your thank-you page or at any stage where your logic marks a user as a customer. It only tracks customers who arrived through one of your affiliates during the valid cookie window. If a visitor didn’t come from an affiliate, nothing is sent to Tapfiliate.

Alternatively, you can use the other methods for the customer creation:

Method: trial

Method example:

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

This method sets the initial customer status to trial. You can read more on customer statuses here.

Method: lead

Method example:

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

This method sets the initial customer status to lead. You can read more on customer statuses here.

Method: conversion

This method tracks a conversion.

This code should be added to the page where the conversion occurs (Thank You page/Order confirmation page). This code will track a conversion only if the current visitor was referred via an affiliate’s referral link within the specified cookie lifetime. For visitors not brought in by an affiliate, no external calls will be made.

Method example:

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

Available arguments:

External_id (optional) - This string value is used to identify a transaction in Tapfiliate. It can assist in cross-referencing the tracking data. In can be any meaningful data for you, usually, it’s an order/transaction ID, a user’s email address, etc. It is also helpful in duplication prevention in tracking. Tapfiliate will not track a conversion if another record with the same external ID already exists.
Amount (optional) - A float argument where you can pass the transaction amount. Tapfiliate will calculate the affiliate commission amount based on this data.

Options

Meta_data (optional) - Metadata for this conversion record, used if you need to attach additional information to conversion details that is not listed within the existing parameters above.

The following limitations apply to metadata:

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

Coupons (optional) - A string coupon code or an array of coupon codes associated with this conversion. Coupon codes take precedence over traffic driven through affiliate links. If none of the supplied coupons are associated with an affiliate, we will fall back on cookie data (if available).
Customer id (required) - Example: USER1234. The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. This ID must be unique for each customer. If you add a customer ID that is already recorded in Tapfiliate, the system will assign the conversion to this customer.
Currency (optional) - A string of a 3-letter currency ICO-code. Useful when handling a program with multiple currencies. If added to the code, it will override the default program currency.
Program_group (optional)(Legacy) - If you are running your account on multiple domains, you can add the program group ID to the conversion code.
always_callback (optional) - A boolean value; set to true to also make your callback fire on failed tracking attempts.

Commission_type (optional) - A string with the commission type identifier. If you are using Extra commissions feature in your program in Tapfiliate, you can specify the commission type identifier in the code to override the standard commission rate.
Callback (optional) - Important: This callback will only fire when a conversion is successfully created.

Method: conversionMulti

This method tracks a conversion with multiple commissions attached. For example, if you want to differentiate the commission amount per category, you can group the orders' line items by category and track a separate commission for each category. Each commission can specify its own commission type identifier.

Method example:

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

Available arguments:

External_id (optional) - This string value is used to identify a transaction in Tapfiliate. It can assist in cross-referencing the tracking data. It can be any meaningful data for you; usually, it’s an order/transaction ID, a user’s email address, etc. It is also helpful for tracking and preventing duplication. Tapfiliate will not track a conversion if another record with the same external ID already exists.

Options

Meta_data (optional) - Metadata for this conversion record, used if you need to attach additional information to conversion details that is not listed within the existing parameters above.

The following limitations apply to metadata:

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

Coupons (optional) - A string coupon code or an array of coupon codes associated with this conversion. Coupon codes take precedence over traffic driven through affiliate links. If none of the supplied coupons are related to an affiliate, we will fall back to cookie data (if any).
Customer id (required) - Example: USER1234. The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. This ID must be unique for each customer. If you add a customer ID that is already recorded in Tapfiliate, the system will assign the conversion to this customer.
Currency (optional) - A string of a 3-letter currency ICO-code. Useful when handling a program with multiple currencies. If added to the code, it will override the default program currency.
Program_group (optional)(Legacy) - If you are running your account on multiple domains, you can add the program group ID to the conversion code.
always_callback (optional) - A boolean value; set to true to also make your callback fire on failed tracking attempts.

Commissions (optional):

Sub_amount (optional) - a number representing the partial order amount for a current commission. Tapfiliate will calculate the affiliate commission amount based on this data.
Commission_type (optional) - A string with the commission type identifier. If you are using the Extra commissions feature in your program in Tapfiliate, you can specify the commission type identifier in the code to override the standard commission rate.

Callback (optional) - Important: This callback will only fire when a conversion is successfully created.

(Advanced) Method: click

You can use this method to create a click based on explicitly supplied tracking parameters. This method is practical when you have a lookup dictionary with affiliate-tracking parameters rather than other values: e.g., a lookup dictionary of affiliate referring domains.

Method example:

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

Available arguments:

Tracking parameters (required) - 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. Example: {referral_code: 'johndoe'} or {asset_id: '1-abcdef', source_id: '2-cdefgh'}
Options:

always_callback (optional) - A boolean value; set to true also to make your callback fire on failed tracking attempts.
Callback (optional) - Important: This callback will only fire when a conversion is successfully created.

How to integrate with Tapfiliate via JavaScript

In this article:

JavaScript integration advantages

JavaScript integration prerequisites

Setting up the JavaScript integration

1. Add the click tracking code.

2. Add the conversion tracking code.

Verify your integration

Additional functionalities of JavaScript integrations

Option 1. Tracking a customer (or a signup)

Option 2. Tracking recurring or lifetime commissions

Option 3. Tracking an alternative commission type (Extra commission)

Option 4. Tracking multiple commissions (conversionMulti method)

Option 5. Attaching metadata to a conversion

Tapfiliate’s JavaScript library 📚

Method: create

Method: detect

Method: customer

Method: conversion

Method: conversionMulti

(Advanced) Method: click