Everflow – Everflow SDK

Docs: Click Tracking

Mon, 01 Jan 0001 00:00:00 +0000

The simplest way to start tracking clicks is to generate a click using the following code :

EF.click({
  offer_id: 1, // Required. The offer id
  affiliate_id: 1, //Required. The affiliate id
});

You may wish to add additional data that will be passed along with the click :

EF.click({
  offer_id: 1, // Required. The offer id
  affiliate_id: 1, //Required. The affiliate id

  uid: 5, // Optional : Offer URL Id
  creative_id: 14, // Optional : Offer Creative ID

  // Optional. Sub placement values.
  sub1: '',
  sub2: '',
  sub3: '',
  sub4: '',
  sub5: '',
  source_id: '',

  coupon_code: '...', // Optional Coupon Code at the click level

  fbclid: '...', // Facebook unique click ID
  gclid: '...', // Google unique click ID
  ttclid: '...', // TikTok unique click ID
});

Extracting data from the URL

When working with direct linking, the affiliate id involved in the click will most likely be dynamic and the value will be passed in the query string of the URL.

The Everflow SDK provides a method to extract any value from the URL. In the following example, the script executes on a landing page where the affiliate id is passed using the affid url parameter : https://destination-url.com?affid=5

EF.click({
  offer_id: 1, // Required. The offer id
  affiliate_id: EF.urlParameter('affid'), //Required. The affiliate id
});

The EF.urlParameter can be used to extract any query string parameter from the URL. For example if the destination URL was instead : https://destination-url.com?oid=3&affid=5&src=facebook&app=mobile, you could use the following code :

EF.click({
  offer_id: EF.urlParameter('oid'), // Required. The offer id
  affiliate_id: EF.urlParameter('affid'), //Required. The affiliate id
  
  sub3: EF.urlParameter('src'), // Optional : "facebook" would be passed as the sub3 in this example
  sub4: EF.urlParameter('app'), // Optional : "mobile" would be passed as the sub4 in this example
  sub5: EF.urlParameter('ref'), // The "ref" query string parameter is missing from the URL. Nothing would be passed as the sub5

});

You can use the Everflow SDK to enhance traditional tracking when you own landing pages. In other words, you can use the Everflow SDK even if you use traditionnal redirect links, which will have the benefit of setting a first-party cookie.

In order to do so, fill the transaction_id parameter when using EF.click. Normally, you would configure your destination url to include the transaction_id, offer_id and affiliate_id macros. Given the following destination url: https://destination-url.com?transaction_id=af189e77650e4e908af797b61b03ac0b&oid=1&affid=5

EF.click({
  offer_id: EF.urlParameter('oid'), 
  affiliate_id: EF.urlParameter('affid'),
  transaction_id: EF.urlParameter('transaction_id')
});

Custom Parameters

It’s also possible to add free form parameters to the click. This is effectively equivalent to adding additional query string parameters to the tracking link URL.

EF.click({
  offer_id: EF.urlParameter('oid'), // Required. The offer id
  affiliate_id: EF.urlParameter('affid'), //Required. The affiliate id

  //Optional. Free form parameters to be appended to the click URL
  parameters: {
    "param1" : "customValue1",
    "param2" : "customValue2" 
  }
})

Attribution in Multi-Tenant Scenarios

While the Everflow SDK does support multiple accounts generating clicks on the same page, it’s important to understand that it does present its own set of challenges. The SDK relies on browser features like cookies to store the transaction IDs necessary for attribution.

The SDK was built with single-tenant usage in mind and may require a little custom work in order to attribute conversions to the right click, especially in scenarios where both networks use the same offer ID.

Please read the Domains Configuration page for more details on how to configure the SDK in such scenarios.

The following sections (“Fetching The Transaction ID” and “Extracting The Transaction ID”) should give you enough information to come up with an attribution strategy that works for your multi-tenant scenario.

Advanced Use

Fetching The Transaction ID

Clicks are identified by unique transaction IDs in Everflow. There are scenarios in which it can be useful to make use of that transaction ID immediately after generating a click.

The EF.click method returns a Promise which, when resolved, will give the transaction ID :

EF.click({
  offer_id: EF.urlParameter('oid'), 
  affiliate_id: EF.urlParameter('affid'),
})
.then((transactionId) => {
  // transactionId containts the unique Everflow transaction ID
  console.log(transactionId)
});

Extracting The Transaction ID

It’s also possible to extract the transaction ID of the last click that was generated using EF.click for a given user. This can be useful in scenarios where, for example, the user initially lands on the following URL : https://destination-url.com/page-A?oid=3&affid=5. The click is generated using

EF.click({
  offer_id: EF.urlParameter('oid'), 
  affiliate_id: EF.urlParameter('affid'),
});

If the user later navigates to https://destination-url.com/page-B, you can access the transaction ID by executing

var offerId = 3;
var efTid = EF.getTransactionId(offerId);

The EF.getTransactionId method will return the latest transaction ID found. It will return an empty string if no transaction ID is found.

You can also access the latest transaction id for a specific advertiser ID, regardless of the offer ID.

var advertiserId = 1;
var efTid = EF.getAdvertiserTransactionId(advertiserId)

Conditional Clicks and Parameters

Of course, being able to extract the transaction ID means that you can add some conditional logic around the way your generate your clicks. For example, if you wish to generate a click only when there are no other transaction IDs stored in the user’s browser, you could add the following logic :

var offerId = 3;
var previousTransactionId = EF.getTransactionId(offerId);

if (!previousTransactionId) {
  EF.click({
    offer_id: offerId, 
    affiliate_id: EF.urlParameter('affid'),
  });
} else {
  // The user has already been on this page and already has the previousTransactionId
  // stored in the browser
}

Similarly, there may be situations in which you wish to attribute a click to “default values” if, for example, no offer id or affiliate id is supplied in the URL

var DEFAULT_OFFER_ID = 1;
var DEFAULT_AFFILIATE_ID = 10;

var offerId = EF.urlParameter('oid'); //Try and extract `oid` from the URL
if (!offerId) {
  offerId = DEFAULT_OFFER_ID; //Default to offer ID 1 if nothing was supplied in the URL
}

var affiliateId = EF.urlParameter('affid'); //Try and extract `affid` from the URL
if (!affiliateId) {
  affiliateId = DEFAULT_AFFILIATE_ID; //Default to affiliate ID 10 if nothing was supplied in the URL
}

EF.click({
  offer_id: offerId, 
  affiliate_id: affiliateId,
});

Docs: Conversion Tracking

Mon, 01 Jan 0001 00:00:00 +0000

Conversions can also be tracked using the Everflow SDK using the following code :

EF.conversion({
  offer_id: 1, // The offer id. Required if aid is not provided
  aid: 2, // The advertiser id. Required if offer_id is not provided
  transaction_id: '', // Optional. The Everflow unique transaction id
})

While the transaction_id is optional, providing it is always more reliable if you have access to it. When the value is missing, the SDK tries to locate it using :

First Party Cookie
Third Party Cookie (on the tracking domain)

Additional options may be used on the EF.conversion method :

EF.conversion({
  offer_id: 1, // The offer id. Required if aid is not provided
  aid: 2, // The advertiser id. Required if offer_id is not provided
  transaction_id: '', // Optional. The Everflow unique transaction id

  amount: 0, // Optional. Sale Amount -- relevant for RPS offers

  event_id: 0, // Optional. The event id
  coupon_code: '', // Optional. Coupon code

  adv_event_id: 0, // Optional. If you use global advertiser events

  order_id: '', // Optional
  user_id: '', // Optional. User tracking

  verification_token: '', // Required if the advertiser is configured to use verification tokens
  email: '', // Optional

  // Optional. Adv placement values.
  adv1: '',
  adv2: '',
  adv3: '',
  adv4: '',
  adv5: '',
})

Custom Parameters

It’s also possible to add free form parameters to the conversion. This is effectively equivalent to adding additional query string parameters when using server postbacks.

EF.conversion({
  offer_id: 1, // The offer id. Required if aid is not provided
  aid: 2, // The advertiser id. Required if offer_id is not provided
  transaction_id: 'af189e77650e4e908af797b61b03ac0b', // Optional. The Everflow unique transaction id
  amount: 19.99, // Optional. Sale Amount -- relevant for RPS offers
  event_id: 23, // Optional. The event id

  //Optional. Free form parameters to be appended to the conversion URL
  parameters: {
    "param1" : "customValue1",
    "param2" : "customValue2" 
  }
})

Advanced Use

Fetching The Transaction ID / Conversion ID

The EF.conversion method returns a Promise which, when resolved, will give you an object that contains both the transaction ID and the conversion ID related to the conversion that was just generated.

EF.conversion({
  offer_id: 1, 
  aid: 2, 
  amount: 9.99, 
  event_id: 11,
})
.then((conversion) => {
  console.log(conversion.conversion_id);
  console.log(conversion.transaction_id)
});

Docs: Impression Tracking

Mon, 01 Jan 0001 00:00:00 +0000

The simplest way to start tracking impressions is to generate an impression using the following code :

EF.impression({
  offer_id: 1, // Required. The offer id
  affiliate_id: 1, //Required. The affiliate id
});

You may wish to add additional data that will be passed along with the impression :

EF.impression({
  offer_id: 1, // Required. The offer id
  affiliate_id: 1, //Required. The affiliate id

  // Optional. Sub placement values.
  sub1: '',
  sub2: '',
  sub3: '',
  sub4: '',
  sub5: '',
  source_id: '',

  fbclid: '...', // Facebook unique click ID
  gclid: '...', // Google unique click ID
});

Extracting data from the URL

When working with direct linking, the affiliate id involved in the impression will most likely be dynamic and the value will be passed in the query string of the URL.

EF.impression({
  offer_id: 1, // Required. The offer id
  affiliate_id: EF.urlParameter('affid'), //Required. The affiliate id
});

EF.impression({
  offer_id: EF.urlParameter('oid'), // Required. The offer id
  affiliate_id: EF.urlParameter('affid'), //Required. The affiliate id
  
  sub3: EF.urlParameter('src'), // Optional : "facebook" would be passed as the sub3 in this example
  sub4: EF.urlParameter('app'), // Optional : "mobile" would be passed as the sub4 in this example
  sub5: EF.urlParameter('ref'), // The "ref" query string parameter is missing from the URL. Nothing would be passed as the sub5

});

Custom Parameters

It’s also possible to add free form parameters to the impression. This is effectively equivalent to adding additional query string parameters to the tracking link URL.

EF.impression({
  offer_id: EF.urlParameter('oid'), // Required. The offer id
  affiliate_id: EF.urlParameter('affid'), //Required. The affiliate id

  //Optional. Free form parameters to be appended to the impression URL
  parameters: {
    "param1" : "customValue1",
    "param2" : "customValue2" 
  }
})

Multiple Everflow Accounts

In a typical scenario where a single Everflow account generates an impression on a page, there is no need to “identify” the account responsible for the impression. The information is inferred from the <script> tag used to include the Everflow SDK. For example :

<script type="text/javascript" 
        src="https://www.TRACKING-DOMAIN-A.com/scripts/main.js"></script>
<script>
  // This click will be attributed to the account that owns "www.TRACKING-DOMAIN-A.com"
  EF.impression({
    offer_id: 1,
    affiliate_id: 1
  });
</script>

Situations may come up where multiple Everflow customers wish to generate impressions on the same page (multi-tenant scenarios). The EF.impression function takes an optional tracking_domain parameter that can be used to associate impressions with specific accounts, regardless of the account that originally imported the script on the page.

<script type="text/javascript" 
        src="https://www.TRACKING-DOMAIN-A.com/scripts/main.js"></script>
<script>
  // This impression will be attributed to the account that owns "www.TRACKING-DOMAIN-A.com"
  EF.impression({
    tracking_domain: "www.TRACKING-DOMAIN-A.com",
    offer_id: 1,
    affiliate_id: 1
  });

  // This impression will be attributed to the account that owns "www.TRACKING-DOMAIN-B.com"
  EF.impression({
    tracking_domain: "www.TRACKING-DOMAIN-B.com",
    offer_id: 50,
    affiliate_id: 17
  });
</script>

More information about multi-tenant scenarios can be found on the Click Tracking page.

Docs: Domains Configuration

Mon, 01 Jan 0001 00:00:00 +0000

The Everflow SDK is served from your account’s tracking domain, which makes it simple to use. You simply need to add :

<script type="text/javascript" 
        src="https://www.YOUR-TRACKING-DOMAIN.com/scripts/main.js"></script>

to your page before you can use the features documented here. This is enough for the vast majority of cases.

However, there are scenarios where the configuration can require additional efforts.

Multiple Everflow Accounts

In a typical scenario where a single Everflow account generates a click on a page, there is no need to “identify” the account responsible for the click. The information is inferred from the <script> tag used to include the Everflow SDK. For example :

<script type="text/javascript" 
        src="https://www.TRACKING-DOMAIN-A.com/scripts/main.js"></script>
<script>
  // This click will be attributed to the account that owns "www.TRACKING-DOMAIN-A.com"
  EF.click({
    offer_id: 1,
    affiliate_id: 1
  });
</script>

Situations may come up where multiple Everflow customers wish to generate a click on the same page (multi-tenant scenarios). The EF.click function takes an optional tracking_domain parameter that can be used to associate clicks with specific accounts, regardless of the account that originally imported the script on the page.

<script type="text/javascript" 
        src="https://www.TRACKING-DOMAIN-A.com/scripts/main.js"></script>
<script>
  // This click will be attributed to the account that owns "www.TRACKING-DOMAIN-A.com"
  EF.click({
    tracking_domain: "https://www.TRACKING-DOMAIN-A.com",
    offer_id: 1,
    affiliate_id: 1
  });

  // This click will be attributed to the account that owns "www.TRACKING-DOMAIN-B.com"
  EF.click({
    tracking_domain: "https://www.TRACKING-DOMAIN-B.com",
    offer_id: 50,
    affiliate_id: 17
  });
</script>

This also gives you the freedom to extract the offer id / affiliate id information from different URL parameters for different accounts should the need arise. A landing page reached via https://landing-page.com?oid=1&affid=2&offer=10&affiliate=17 could lead to :

<script type="text/javascript" 
        src="https://www.TRACKING-DOMAIN-A.com/scripts/main.js"></script>
<script>
  EF.click({
    tracking_domain: "https://www.TRACKING-DOMAIN-A.com",
    offer_id: EF.urlParameter('oid'),
    affiliate_id: EF.urlParameter('affid')
  });
  EF.click({
    tracking_domain: "https://www.TRACKING-DOMAIN-B.com",
    offer_id: EF.urlParameter('offer'),
    affiliate_id: EF.urlParameter('affiliate')
  });
</script>

Important : Subdomains must always be specified when using the tracking_domain parameter as apex domains are considered invalid. Use tracking_domain: "www.domain.com", not tracking_domain: "domain.com"

Cookies, Subdomains and Attribution

The Everflow SDK uses different methods to make the attribution as reliable as possible. For that reason, first party cookies created on the domain where the clicks are initially generated. Information is later extracted from that cookie when a conversion occurs. This requires the cookie to be accessible when the EF.conversion(...) code ultimately runs.

When the click occurs on a subdomain that differs from the one where the conversion occurs, the cookie may not be accessible. For example :

User lands on https://shop.your-store.com which generates a click
The Everflow SDK first party cookies the browser using the shop.your-store.com domain
User decides to make a purchase and is redirected to https://payment.your-store.com
User completes the purchase, which generates a conversion (from https://payment.your-store.com)
The Everflow SDK cannot get access to the first party cookie since it is stored on a different subdomain. It must rely on a different attribution mechanism

In such a scenario, it is preferable to store the cookie on the top level domain (your-store.com) rather than on a subdomain (shop.your-store.com) to avoid attribution problems. This is done by using the EF.configure method. In the scenario described above the click code would look like so :

<script type="text/javascript" 
        src="https://www.YOUR-TRACKING-DOMAIN.com/scripts/main.js"></script>
<script>
  EF.configure({
    tld: "your-store.com" // Top level TLD without http(s)
  });

  EF.click({
    offer_id: 5,
    affiliate_id: EF.urlParameter('affid')
  });
</script>

The conversion code would then make use of the same method to fetch the cookie more reliably, regardless of which subdomain the page lives on :

<script type="text/javascript" 
        src="https://www.YOUR-TRACKING-DOMAIN.com/scripts/main.js"></script>
<script>
  // The EF.conversion code will look through all cookies, including the one set at the top level TLD
  EF.conversion({
    offer_id: 5
  });
</script>

Docs: Organic Tracking

Mon, 01 Jan 0001 00:00:00 +0000

The organic tracking feature can be used if you wish to track clicks and conversions that happened without an explicit offer/affiliate context. Here is a simple example of a click that attempts to gather the offer and affiliate ids from the URL.

In a normal scenario, if any of the parameters are not present, it would result in a failure to fire the click. However, since organic tracking is configured, it would instead end up using the offer and affiliate ids provided.

<script type="text/javascript" 
        src="https://www.TRACKING-DOMAIN.com/scripts/main.js"></script>
<script>
  // Organic tracking settings are configured using the "organic" property.
  EF.configure({
    organic: {
      offer_id: 1,
      affiliate_id: 1
    }
  })

  EF.click({
    offer_id: EF.urlParameter('oid'),
    affiliate_id: EF.urlParameter('affid')
  });
</script>

Everflow – Everflow SDK

Docs: Click Tracking

Extracting data from the URL

ITP Workaround And First-Party Cookie Tracking

Custom Parameters

Attribution in Multi-Tenant Scenarios

Advanced Use

Fetching The Transaction ID

Extracting The Transaction ID

Conditional Clicks and Parameters

Docs: Conversion Tracking

Custom Parameters

Advanced Use

Fetching The Transaction ID / Conversion ID

Docs: Impression Tracking

Extracting data from the URL

Custom Parameters

Multiple Everflow Accounts

Docs: Domains Configuration

Multiple Everflow Accounts

Cookies, Subdomains and Attribution

Docs: Organic Tracking