Installing Trackingplan

Installing Trackingplan on your Websites

📖

In this section:

Installing Trackingplan…

The most common way to install Trackingplan is by using Google Tag Manager or by directly copying the snippet onto your website.

Using Google Tag Manager

If you are using Google Tag Manager, installing Trackingplan on your website can be done even without having access to your site’s code. Here is how:

Log in to Google Tag Manager.
Create a New tag inside the container connected to your website.
Hover over the Tag Configuration box and click on the gray pencil icon.

Next, you can choose the tag type. Select Custom HTML Tag as the tag type.

Now, let’s configure your tag. To do this, paste your Trackingplan snippet into the HTML text box in Google Tag Manager. Remember that you can always retrieve your snippet from https://panel.trackingplan.com/plans/”your TP_ID”/install

Then, set up your tag’s advanced settings. Click Advanced Settings and set Tag firing Priority to 1000 and Tag Firing Options to Once per page to ensure Trackingplan can see events that trigger once the page has loaded.

Next, navigate to the Triggering box and click on the gray pencil icon to choose a trigger. For the best results, select All Pages.

Once saved, Trackingplan will load on any page where the Google Tag Manager container script is installed. Remember to Submit your changes!

👏🏻

All done! After this easy installation, don’t forget to verify that data collection is working to ensure Trackingplan is automatically monitoring and documenting all the customer data you are using for your analytics, marketing, and sales.

GTM Tip: Track GTM Version and ID as a Custom Dimension (Optional)

☝🏻

Any data tagged in your GTM can be added to the Trackingplan script using tags to extend Trackingplan's detection capabilities.

In this sense, to be able to later attribute warnings to configuration changes, show them as releases, and see them in RCA, we recommend you send GTM’s Container Version as tags.

The container version label is standard and can be included just as in the example below.

tags: {
...
"gtm_container_version": "{{Container Version}}"
...
}

Moreover, if you use multiple GTM containers, you can also add the Container ID as a tag. For it, you will need to configure it in GTM first, as indicated in this article.

Add Trackingplan’s Snippet to Your Site

You can also install Trackingplan by adding our snippet to your site. This is how:

☝🏻

Note: If you are not using a content management system (CMS) like Webflow or WordPress, we recommend asking a developer to add the snippet to your pages. Incorrect installation will prevent Trackingplan from detecting relevant data.

Retrieve your snippet from https://panel.trackingplan.com/plans/”your TP_ID”/install

<script type="text/javascript">
    (function(){function a(){try{q.setItem("_tp_t","a"),q.removeItem("_tp_t")}catch(a){return!1}return!0}function b(){var a=Object.getOwnPropertyDescriptor(HTMLImageElement.prototype,"src").set;Object.defineProperty(HTMLImageElement.prototype,"src",{set:function(b){return e({method:"GET",endpoint:b,protocol:"img"}),a.apply(this,arguments)}});var b=HTMLImageElement.prototype.setAttribute;HTMLImageElement.prototype.setAttribute=function(a,c){return"src"==a.toLowerCase()&&e({method:"GET",endpoint:c,protocol:"img"}),b.apply(this,arguments)}}function c(){var a=t.prototype.open,b=t.prototype.send;t.prototype.open=function(b,c){return this._tpUrl=c,this._tpMethod=b,a.apply(this,arguments)},t.prototype.send=function(a){return e({method:this._tpMethod,endpoint:this._tpUrl,payload:a,protocol:"xhr"}),b.apply(this,arguments)}}function d(){var a=navigator.sendBeacon;navigator.sendBeacon=function(b,c){return e({method:"POST",endpoint:b,payload:c,protocol:"beacon"}),a.apply(this,arguments)}}function e(a){setTimeout(function(){try{var b=n(a.endpoint);if(!b)return;var c=l();return!1===c?(G.push(a),o("Queued, queue length = "+G.length),setTimeout(j,C),!1):g(E,c)?(f(h(a,b,c.sampleRate),y),!0):(o({message:"Request ignored (sampling)",mode:E,dict:c}),!0)}catch(b){p({message:"Trackingplan process error",error:b,request:a})}},0)}function f(a,b){function c(a){var b=A+"?data="+encodeURIComponent(btoa(JSON.stringify(a))),c=document.createElement("img");c.src=b}function d(a){navigator.sendBeacon(A,JSON.stringify(a))}function e(a){var b=new XMLHttpRequest;b.open("POST",A,!0),b.onreadystatechange=function(){if(4===b.readyState)try{o({message:"TP Parsed Track",response:JSON.parse(b.response)})}catch(a){}},b.send(JSON.stringify(a))}o({message:"TP Sent Track",rawEvent:a});"img"===b?c(a):"xhr"===b?e(a):"beacon"===b?d(a):void 0}function g(a,b){switch(a){case"user":return 1===b.isSampledUser;case"track":return Math.random()<1/b.sampleRate;case"all":return!0;case"none":default:return!1;}}function h(a,b,c){return{provider:b,request:{endpoint:a.endpoint,method:a.method,post_payload:a.payload||null},context:{href:r.location.href,hostname:r.location.hostname,user_agent:navigator.userAgent},tp_id:v,source_alias:x,environment:w,sdk:H.sdk,sdk_version:H.sdkVersion,sampling_rate:c,debug:z}}function i(){for(;G.length;){var a=G.shift();e(a)}}function j(){if(!F){var a=new XMLHttpRequest,b=B+"config-"+v+".json";a.onreadystatechange=function(){if(4==this.readyState)try{k(JSON.parse(this.responseText).sample_rate),i()}catch(a){}F=!1},a.open("GET",b,!0),F=!0,a.send()}}function k(a){if(!1===a)return q.removeItem("_trackingplan_sample_rate"),q.removeItem("_trackingplan_sample_rate_ts"),void q.removeItem("_trackingplan_is_sampled_user");var b=Math.random()<1/a?1:0;o("Trackingplan sample rate = "+a+". isSampledUSer "+b),q.setItem("_trackingplan_sample_rate_ts",new Date().getTime()),q.setItem("_trackingplan_sample_rate",a),q.setItem("_trackingplan_is_sampled_user",b)}function l(){var a=q.getItem("_trackingplan_sample_rate_ts");return null!==a&&(parseInt(a)+1e3*D<new Date().getTime()?(o("Trackingplan sample rate expired"),k(!1),!1):{sampleRate:parseInt(q.getItem("_trackingplan_sample_rate")),isSampledUser:parseInt(q.getItem("_trackingplan_is_sampled_user"))})}function m(b,c){for(var d in c)b[d]=c[d];return b}function n(a){for(var b in u)if(-1!==a.indexOf(b))return u[b];return!1}function o(a){z&&s.log(a)}function p(a){r.console&&s.warn&&s.warn(a)}var q=localStorage,r=window,s=console,t=r.XMLHttpRequest;if(r.Trackingplan)return void p("Trackingplan snippet included twice.");var u={"google-analytics.com":"googleanalytics","segment.com":"segment","segment.io":"segment","quantserve.com":"quantserve","intercom.com":"intercom",amplitude:"amplitude",appsflyer:"appsflyer",mixpanel:"mixpanel",kissmetrics:"kissmetrics","hull.io":"hull"},v=null,w="PRODUCTION",x=null,y="xhr",z=!1,A="https://tracks.trackingplan.com/",B="https://config.trackingplan.com/",C=0,D=86400,E="user",F=!1,G=[],H=r.Trackingplan={sdk:"js",sdkVersion:"1.4.1",init:function(e,f){f=f||{};try{if(!a())throw new Error("Not compatible browser");v=e,w=f.environment||w,x=f.sourceAlias||x,y=f.sendMethod||y,u=m(u,f.customDomains||{}),z=f.debug||z,A=f.tracksEndPoint||A,B=f.configEndPoint||B,C=f.delayConfigDownload||C,D=f.sampleRateTTL||D,E=f.samplingMode||E,b(),c(),d(),o({message:"TP init finished with options",options:f})}catch(a){p({message:"TP init error",error:a})}}}})();
    Trackingplan.init("YOUR_TP_ID");
</script>

This minified example is only for documentation purposes. To retrieve your Trackingplan’s snippet, you need to create an account first. Then, replace YOUR_TP_ID with your personal Trackingplan ID.

Paste the snippet into the top of the <head> section of all of your pages, before any other analytics snippets or tracking codes.

Once installed and after verifying that Trackingplan is collecting data correctly Trackingplan will automatically verify the data you send to your third-party services without modifying or slowing anything down.

How it Works

This will ensure your tracking plan is always updated and any inconsistencies or errors can be easily identified. Trackingplan SDK attaches a listener to all the remote tracking requests emitted by your analytics providers’ SDKs. This listener works in the background as non-blocking and, therefore, does not interfere with the original request that the provider's client makes.

The technical procedure for listening to the requests is very simple: The JavaScript methods used to make the requests are wrapped by our code. This way, when the analytics services use them to send the tracking info, two things happen:

First, the original action is performed (i.e. the request is sent to the analytics provider).
In a non-blocking manner, and only if the request URL matches with a known analytics services domain, the request is forwarded to our server.

Here’s what our script listens to, which includes the three most typical methods used to communicate with analytics providers:

XHR: by wrapping the XMLHttpRequest.open and XMLHttpRequest.send functions
Pixels: by wrapping the HTMLImageElement.prototype.setAttribute function
Beacons: by wrapping the navigator.sendBeacon function

☝🏻

Note that the used implementation is similar to the one used in your actual analytics providers, and also employed in the case of browser extensions, testing suites, and debugging tools.

Advanced options

Trackingplan’s init call can also receive an options dictionary, allowing you to set some advanced parameters to differentiate between sources, environments, and custom domains, or enhance Trackingplan’s debugging capabilities

Parameter	Description	Default value	Example
`sourceAlias`	Allows to differentiate between sources	`Javascript`	`IOS App`
`environment`	Allows to isolate the data between production and testing environments	`PRODUCTION`	`DEV`
`customDomains`	Allows to extend the list of monitored domains. Any request made to these domains will also be forwarded to Trackingplan. The format is `{"myAnalyticsDomain.com": "myAnalytics"}`, where you put, respectively, the domain to be looked for and the alias you want to use for that analytics domain.	`{}`	`{"mixpanel.com": "Mixpanel"}`
`debug`	Shows Trackingplan debugging information in the console	`false`	`true`
`tags`	Tags allow you to label the data you send to Trackingplan. These are completely customizable, enabling you to distinguish your warnings by their `release version`, `build number` `app version`, `test name`, etc., debug and perform root-cause analysis on your warnings, or break down event traffic by the values of your tags (`country`, `pageType`, etc.)	`empty`	`"country": "us"`

All you need to do to set up tags is to add the following init(...) parameter in the Trackingplan’s snippet you already used to install Trackingplan in your site code or your Google Tag Manager:

Trackingplan.init(..., {
	"tags": {
		"tagName1": "tagValue",
		"tagName2": "tagValue",
		...
	}
})

After this easy setup, all the traffic that will arrive at Trackingplan from your sites and apps will be labeled with these customizable tags.

Content Security Policies

Content Security Policies are delivered as a header to your users' browsers by your web server and are used to declare which dynamic resources are allowed to load on your page.

For many websites, this is often as straightforward as declaring that only scripts/styles from your domain and the tools you use are allowed. However, this can become more intricate when complex setups are in play.

If you are using a default Content Security Policy (CSP), add config.trackingplan.com to your script-src policy.

default-src ... *.trackingplan.com 'unsafe-inline'

If you want stricter restrictions, add tracks.trackingplan.com to your connect-src policy. We recommend the template below to ensure your policies are more future-proof. Here's an example of what that would look like:

connect-src ... *.trackingplan.com

Do you have more questions? Problems? Need more info? We can help! Contact us and we’ll get to you as soon as possible.

← Previous

Installing Trackingplan

Webhooks

For Websites