Permutive can collect data on users off-site. There are many cases where this can be useful, for example if you want to:

  • Track a PartnerConversion event when a user visits your partner's site and has converted on a campaign.
  • Track an EmailOpen  event when a user opens a marketing email.
  • Track an AdImpression  event, when a user views an advertising campaign either off-site or within an isolated iframe or video player.

In the case of impression and conversion tracking, this can be especially useful for:

  • Reporting back on the performance of a campaign after it has run
  • Optimising during the campaign to make sure you reach conversion KPIs
  • Removing users from targeting segments if they have already converted
  • Offering premium targeting for users who have visited the partner site but not yet converted

These types of off-site events are typically tracked by firing pixels. These are small HTTP requests that are made to Permutive and enable us to register an event against a user ID.

Identifying Users

A prerequisite to setting up a pixel is to first know how you will identify the user in Permutive, when your pixel fires. There are generally two options for doing this:

  1. Rely on a third-party cookie. We typically use AppNexus's third-party cookie for tracking user's across the web. This is very effective, but has the downside of only working in environments where third-party cookies are permitted. 
  2. Use your own internal user ID. This option is not always feasible, but if you are passing your own internal user IDs into Permutive (e.g. using Permutive aliases) - you can use these aliases in the pixel URL to enable us to identify the user.

Note: in order to rely on a third-party cookie, third-party tracking must first be enabled on your Permutive project. If unsure whether this feature has been enabled, please reach out to support@permutive.com for us to enable this.

Implementing Pixels

Generally, there are three ways to implement and deploy a pixel: by passing a tracking URL into a third-party platform, by deploying a JavaScript tag on-site or via an HTML image element. We will discuss each approach in this section.

We recommend you email support@permutive.com for help in setting up your pixels and to ensure the pixel is deployed correctly.

Method 1: Generate a Tracking URL

This method is commonly used when you just need a pixel URL that can be copied and pasted into a third-party platform. The third-party platform will then handle the process of making the pixel request and sending the event into Permutive.

In future, we intend to make the process of generating pixel URLs easier - however currently, we recommend you generate pixel URLs by executing the below JavaScript snippets in your web browser console.

If relying on a third-party cookie:

var publicKey = '<PUBLIC_API_KEY>';
var eventName = '<EVENT_NAME>';
var eventProperties = {
    <EVENT_PROPERTIES_AS_JSON>
};
console.log("https://ib.adnxs.com/getuid?" + encodeURI("https://api.permutive.com/v2.0/px/track?k=" + publicKey + "&i=$UID&e=" + eventName + "&p=" + encodeURIComponent(JSON.stringify(eventProperties)) + "&it=appnexus"));


If relying on your own internal user IDs:

var publicKey = '<PUBLIC_API_KEY>';
var eventName = '<EVENT_NAME>';
var aliasId = '<ALIAS_ID>';
var aliasTag = '<ALIAS_TAG>';
var eventProperties = {
    <EVENT_PROPERTIES_AS_JSON>
};

console.log("https://api.permutive.com/v2.0/px/track?k=" + publicKey + "&i=" + aliasId + "&e=" + eventName + "&p=" + encodeURIComponent(JSON.stringify(eventProperties)) + "&it=" + aliasTag);


 In the above snippets, be sure to replace <PUBLIC_API_KEY> , <EVENT_NAME>  and <EVENT_PROPERTIES_AS_JSON> appropriately.

For the latter snippet, replace <ALIAS_ID>  and <ALIAS_TAG>  with your internal user ID and the tag used for this type of user ID within Permutive. If you are using our JavaScript SDK's permutive.identify method to pass these aliases to Permutive, your aliases will be tagged as default.

Method 2: JavaScript Tags

This method can be used to generate a JavaScript tag, which can be implemented on websites to appropriately fire events into Permutive when a user either views an element or performs an action. These tags are commonly used to track off-site conversions or on-site events from within an isolated iframe or video player. 

The JavaScript tag looks similar to the above, except it is code that can be deployed on-site and will actually initiate the pixel fire.

<script>
var publicKey = '<PUBLIC_API_KEY>';
var eventName = '<EVENT_NAME>';
var eventProperties = {
    <EVENT_PROPERTIES_AS_JSON>
};

var protocol = 'https:' == document.location.protocol ? 'https:' : 'http:';
(new Image()).src = protocol + "//ib.adnxs.com/getuid?" + encodeURI(protocol + "//api.permutive.com/v2.0/px/track?k=" + publicKey + "&i=$UID&e=" + eventName + "&p=" + encodeURIComponent(JSON.stringify(eventProperties)) + "&it=appnexus&rand=" + Math.round(Math.random() * 1000000));
</script>

Note that in this tag, we append a rand  parameter to the URL along with a randomly generated number. This acts as a cache buster to ensure the pixel request will always reach the Permutive API. 


For tracking off-site conversions, your partner needs to deploy a JavaScript tag on the conversion page of their site.

Example: Here we provide an example JavaScript tag that can be used for tracking off-site conversions, by sending a PartnerConversion event to Permutive. It doesn't contain any additional information about the conversion itself, but will contain the URL of your partner's landing page. This tag relies on AppNexus's third-party cookie for user identification.

<script>
var publicKey = 'f4315c49-5695-4b18-b0ed-6796643af237';
var eventName = "PartnerConversion";
var eventProperties = {
    url: (window.location.href ? window.location.href : '')
};

(new Image()).src = "https://ib.adnxs.com/getuid?" + encodeURI("https://api.permutive.com/v2.0/px/track?k=" + publicKey + "&i=$UID&e=" + eventName + "&p=" + encodeURIComponent(JSON.stringify(eventProperties)) + "&it=appnexus&rand=" + Math.round(Math.random() * 1000000));
</script>

Note: This exact same pixel tag can be used for multiple partners - as the partner name can be inferred from the URL.

Example: Here we show a slightly more complex JavaScript tag that includes additional custom properties on each event. 

Again, this example fires a PartnerConversion event to Permutive, but this time we include some additional properties about each conversion: the partner name and conversion value. A developer can choose to dynamically populate these properties depending on the page and context, if necessary.

<script>
var publicKey = "f6515c49-5695-4b18-b0ed-6796643af237";
var eventName = "PartnerConversion";
var eventProperties = {
    partner: "Site A",
    value: 50.0
};

var protocol = 'https:' == document.location.protocol ? 'https:' : 'http:';
(new Image()).src = protocol + "//ib.adnxs.com/getuid?" + encodeURI(protocol + "//api.permutive.com/v2.0/px/track?k=" + publicKey + "&i=$UID&e=" + eventName + "&p=" + encodeURIComponent(JSON.stringify(eventProperties)) + "&it=appnexus&rand=" + Math.round(Math.random() * 1000000));
</script>

Method 3: HTML Image Elements

The final method for deploying tracking pixels is to use a 1x1 HTML image element. This method is most commonly used in emails, where HTML is permitted but JavaScript tags are not. 


For this method, you must first generate a pixel URL using the steps described in our Generate a Tracking URL section above. Once you have this, the URL can be inserted into an HTML image tag as follows:

<img src="<TRACKING URL>" height="1" width="1" border="0" />


For example, if our pixel URL is https://ib.adnxs.com/getuid?https://api.permutive.com/v2.0/px/track?k=f6515c49-5695-4b18-b0ed-6796643af237&i=$UID&e=PartnerConversion&p=%257B%2522partner%2522%253A%2522Site%2520ABC%2522%252C%2522value%2522%253A50%257D&it=appnexus, the HTML image tag would look like:

<img src="https://ib.adnxs.com/getuid?https://api.permutive.com/v2.0/px/track?k=f6515c49-5695-4b18-b0ed-6796643af237&i=$UID&e=PartnerConversion&p=%257B%2522partner%2522%253A%2522Site%2520ABC%2522%252C%2522value%2522%253A50%257D&it=appnexus" height="1" width="1" border="0" />


Note: Similar to our JavaScript tags, we recommend appending a
rand  parameter to the URL to act as a cache buster, where possible. This may be possible in certain email automation platforms.

Using This Data

Once you have collected this data in Permutive, we can set up custom reporting for you on the conversions, as well as help you create segments based on these events. 

Did this answer your question?