Deploying the Permutive JavaScript Tag

In this article

A general guide to successfully deploying the Permutive tag.

Overview

Integrating Permutive with your website is simple. The deployment consists of deploying a JavaScript tag on your website, after which Permutive will begin collecting event data. Once deployed, you can enable and configure our integrations with your favorite tools.

For new customers, our team will typically work closely with you to configure the tag to pick up details about your content. Finally, we'll work with you to verify a successful deployment.

Prerequisites

Permutive Project - You should already have a Permutive project. If you are not yet a customer, get in touch!
Public API Key - You should have a public API key assigned to your Permutive project. An API key is automatically created on all new projects and can be found in the dashboard.
Web Addon - Your project should have the web addon enabled. This addon is enabled on all new projects by default - however, you can check this in the dashboard.

Setup

The JavaScript Tag

Our team will provide you with the latest version of the Permutive JavaScript tag. The tag will look similar to the below example but will be configured for deployment on your site.

The Permutive JavaScript tag should be deployed on your website on all pages where you want Permutive to run. The basic version of our tag enables our default web collectors which will track a set of basic events, such as Pageviews:

<script>
  !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>",{});
  window.googletag=window.googletag||{},window.googletag.cmd=window.googletag.cmd||[],window.googletag.cmd.push(function(){if(0===window.googletag.pubads().getTargeting("permutive").length){var e=window.localStorage.getItem("_pdfps");window.googletag.pubads().setTargeting("permutive",e?JSON.parse(e):[]);var o=window.localStorage.getItem("permutive-id");o&&(window.googletag.pubads().setTargeting("puid",o),window.googletag.pubads().setTargeting("ptime",Date.now().toString())),window.permutive.config.viewId&&window.googletag.pubads().setTargeting("prmtvvid",window.permutive.config.viewId),window.permutive.config.workspaceId&&window.googletag.pubads().setTargeting("prmtvwid",window.permutive.config.workspaceId)}});
  permutive.addon('web', {});
</script>
<script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>

Note: you must ensure you replace all occurrences of ORGANIZATION_ID, WORKSPACE_ID, and WORKSPACE_API_KEY appropriately. If you are unsure, please contact support

Best Practices

When deploying the script, ensure it is placed in between your <head> and </head> tags on each page. We recommend our customers deploy Permutive early on the page, i.e. above other scripts in the <HEAD> section where possible. This helps ensure Permutive loads as quickly as possible and is able to update targeting information on the page. This is especially important when using our advertising integrations, as we need to process data in real time before ad requests are made.

We strongly recommend against deploying our tag via tag managers, such as GTM. While Permutive can be deployed in this way, doing so can cause significant delays and prevent Permutive from loading quickly. Note that our script loads asynchronously, so should not impact page load times or page performance.

DFP / Google Ad Manager

Many of our customers use Permutive's Google Ad Manager integration. If you intend to use the GAM integration in the future, an additional deployment step is needed at this stage.

We recommend all customers deploy a small piece of JavaScript that reads Permutive targeting data from the browser cache and ensures it is passed into GAM early on page load. By doing this, we can guarantee that cached Permutive cohorts are sent into GAM on every ad request.

The JavaScript required for this is shown below. This script should be placed after googletag is defined but before a call is made to googletag.enableServices() .

<script>
window.googletag = window.googletag || {}
window.googletag.cmd = window.googletag.cmd || []

window.googletag.cmd.push(function() {
  if (window.googletag.pubads().getTargeting('permutive').length == 0) {
    var kvs = window.localStorage.getItem('_pdfps');
    window.googletag.pubads().setTargeting('permutive', kvs ? JSON.parse(kvs) : []);
  }
});
</script>

Note: This article assumes that you already have a Permutive project and have been provided with our JavaScript tag for deployment on-site. If this is not the case, then please get in touch!

For more information on the technical details and advanced deployment options, please see our developer docs.

Search

Publisher Support