How To¶
The tag project is one of our oldest in the Cubed platform. It goes hand in hand with the DCS really as they both need to "agree" on the data being passed up. The DCS uses the SchemaValidation class to check if what the tag has sent is legal and correct for insertion.
The tag is split into 3 files which get merged together automatically while build.py is running. The 3 files are: tag_config.js, tag_pre.js, and tag_post.js.
This was done as a way to allow clients to have their own version of the tag, but we ditched this idea a long time ago. These 3 files could now be 1 and make the development process much easier and cleaner.
However, with the tag split out into 3 files, it does make it easier to discuss.
Tag Config¶
This is the base function reset() which is called after the tag is first loaded. It preapres the internal state object with default settings before any client-side JS can run and change.
Tag Pre¶
This holds all the Cubed speciifc variables we want to define, and any functions we didn't want to change on a client by client basis.
The main properties here are: tagVersion, defaultFwdParams and defaultIgnoredURLs.
tagVersion¶
This helps us track which tag is currently live and being used on clients sites. The idea is all clients use the same tag version, so when we deploy this number should be the same for all.
Note
This is also used as a "blocker" when deploying. If you havent incremented this number, you will not be able to deploy.
defaultFwdParams¶
The "forward params" part of Cubed is very important. This is what our entire Channels system is built on. Each Channel has Pattern(s), which are regex strings checking the referer property we send up. A "forward param" is a query param we can "find" in the URL and append to the current visitor's document.referer. This is because a lot of companies use landing page query params to track visitors.
The most obvious, and first in the list, is gclid. This is a "google click id", and is appended to all PPC links. So when someone clicks a PPC link from a Google search page, they arrive on a client's website with document.referer saying https://www.google.com and a landing page saying www.client.com/landing-page?gclid=abc1234.
When the Cubed tag runs it will find all "forward params" in the landing page URL and append them to the referer string, meaning our visitor's document.referer now looks like this: https://www.google.com?gclid=abc124
This can be added to by using the addForwardParams functions when the tag is deployed on client's sites.
defaultIgnoredURLs¶
This array is used to "ignore" visitor's coming from third party payment sites.
Note
This needs to be reviewed as it might not be needed anymore.
Tag Post¶
This holds everything the tag needs to run correctly. We need to flesh out the docs here in how it all works, but a lot of the functionality is explained via the Tagging Docs.
There are also some good examples in the test.html file too, to help explain the steps involved in things like handleSplitVisit etc...
The main concept of these functions are: we want to set a long lasting cookie for the Visitor vscr_vid and a normal session (short term) cookie for the Visitor's Visit vscr_sid. To do this we call setFirstPartyCookies which will use getCookieDomain to find the best domain to use for our cookies.
We also want to track Visitor's going across domains, but still under the umbrella of this client. To do this we append the ydat query param to all "exit links". This is done via the appendYdat function, which in turn uses the state.endpoints array. To add to this the client would use the tag function addEndPoint
The tag comes with some built in debugging functions, such as printLog, and setSimulate, along with enterDebug and exitDebug modes.
If you setSimulate as true then the tag will fire to production but the Data Collection Server will NOT insert it. This means you can test without inflating visit hits in the DB.
The printLog function will simply print all "logs" we've stored. Every function in the tag can, and will, call vscr.<logging type>(). We support the following logging types: log, info, warning, success and error. These can be used by calling vscr.info("added a thing");