Hit attributes

"hit" is the name of the events Keytiles receives through the Hit Collection API - representing the fact that something has happened somewhere in the content. At this point Keytiles needs to know what has happened on which content so we can track this fact accordingly.

In this article we describe the attributes of the hit - so you know better which attribute means what exactly.

Content of this page

Before you start...

... there is one thing we should clarify and you should understand.

Maybe the most important difference between Keytiles and other analytics tools is that for Keytiles your content is not just a flat list of URLs...

A typical web analytics tool is going with a simple logic: content = URL.

What does a URL represent in reality exactly? (...which is actually pretty important to know to see behind those numbers) It's your problem to know! And we are pretty sure that you all experienced very practical problems already here while opening those traditional dashboards looking at the list of your tracked content... Duplicated / triplicated entries - actually meaning the same. Unrecognizable machine-provided noise in URLs. Sounds familiar? We try to eliminate all of these!

The TileView of Keytiles is efficient because

Keytiles is thinking in structured content - where structured content = a content tree basically
therefore it can go with the Treemap visualization - which is simply naturally much better understandable by humans than endless list of URLs when you want to get an efficient overview about "what is going on now?"

"tile" - what is this?

The term "tile" comes from the TileView visualisation of Keytiles actually. A "tile" is a content - which appears on this UI as a "tile". That's where it is coming from. It can be an article, a user profile, a file etc - literally anything which lives on your website and you want to track it. It's actually up to you what fits the most to your needs.

By default when you install Keytiles the most basic way it is the page which is loaded on the URL the visitor visits. But of course you can customize the tracking using advanced techniques too driven by JavaScript in your website. Or by your native app interacting with your web content.

Attribute reference

eventType

default / fallback value: "pageview"
type: string
max length: keep this short if possible - but there is no strict limit
possible values: any (free text) - but can not be empty

Tells Keytiles what has happened over the content (Tile).

By default (by our Tracking Script) the eventType=pageview. But it can be others like "view", "download", "login"/"logout", etc etc. which makes sense over the tileType the event happened on.

Actually, it can be really anything. You can even fully customize this and implement your own event types easily by just simply sending in something. You can send in eventType=my-custom-event-name.

You can check our article How does event tracking and micro conversion work? to learn a bit more about it.

tileId

type: string
max length: try to fit into 24-32 chars with this - but there is no strict limit
possible values: any (free text) - but can not be empty

The unique ID of the content (entity) Keytiles can use to recognize the entity (regardless the URL) and track it correctly.

If your site is CMS backed then consider to use the entity ID coming from the CMS in this field - if this is a concrete entity. If this is a logical entity, e.g. your "frontpage" (so probably even generated) then go with the logical name instead. In this case "frontpage" is a very valid tileId actually ...

tileType

default / fallback value: "article"
type: string
possible values: any (free text) - but can not be empty and you should not use spaces and/or "weird" characters in it (however technically they will not cause any issues)

The type of the content.

The current version of our TileView only supports "frontpage", "page" and "article" as we speak! This is because of historical reasons.

We will enhance this in the future definitely. If this is a blocker for you please reach out to us in one of our contact channels and we can prio this up!

There are many benefits we can reach by knowing and differentiating your content entities based on their roles in the content structure - in other terms knowing "which type" a certain content is exactly.

Keytiles is pre-defined a few major types you can use but you can also create your own types if that is a better fit for your use case.

The pre-defined types are the following:

frontpage

It's pretty self-explanatory isn't it? If a visitor is going top-to-bottom direction then this is the main entry point into your content.

A frontpage is building a navigation around all your contents - and acts as the very first decision point for the visitor regarding in which direction (s)he wants to continue browsing your content.

Frontpage is always an important and special place for all websites.

page

Similar to the frontpage in a sense it is still representing entry point of a collection of articles - but already representing a more specific grouping of them.

For example: on a news website the "Sport" or "Tech" page is bringing together articles which are about "Sport" and "Tech" topics.

Very valuable too - just mentioning one example: if you want to target some specific messages / ads.

article

This type is used as a "default" if you do not send in any tileType attribute.

This is often a "leaf" type in your content tree. The visitor will not really go deeper at this point in the structure. Max (s)he will step to a related article (whatever "related" means at this point).

It is a good idea to check our Example use-cases for attribute values section below.

file

You can use this for files - many websites are offering different files for download / view.

form

Do you have a registration form? Or a subscribe form? Or any other? Then you can use this type in these places maybe.

post

Can be a good fit for many things but typically posts are created by users on a website. Sometimes author of blogs. But you can also consider simply using "article" type for all of these.

comment

Can be used if users making comments on your page and you want to track them.

profile

If you have users and visitors can view their profile data then this type could be used.

tileGroupPath

default / fallback value: "/" - so tile will go to the root level of the structure in this case
type: string
max length: you should fit into 200 chars with this - but there is no strict limit
possible values: like a file system path - must start with "/" and should not have trailing "/" character, neither empty fractions like "//" or "/ /"

This is an "/a/b/c" like string - defining the path in your content structure the content belongs to.

If the tileType value is "frontpage" then please make sure you put "/" into this!

It is important to understand the concept of this attribute so please take a few minutes and check the Example use-cases for attribute values section below! Misusing this attribute will really have an impact on your Keytiles tracking quality!

tileLanguage

default / fallback value: the language code provided by the page like "lang='xy'"
type: string
max length: 2 (due to ISO-639-1 standard)
possible values: just Google for the above language standard

Optional field. You can send in an ISO-639-1 two letters language code e.g. 'en'.

This would let Keytiles know in which language your visitor has viewed the tile.

tileTitle

default / fallback value: the OpenGraph og:title <meta> tag (in the page) if present, if not then <head>/<title> tag in the page
type: string
max length: try to fit into 32 chars with this - but there is no strict limit
possible values: any (free text) but should not be empty

The title of your content this - when it appears as a "tile" under the structural point described by the tileGroupPath attribute

It is a valid use-case if the title of your Tile is slightly different depending on under which tileGroupPath it appears at the moment. So Keytiles is tracking the titles accordingly.

It is important to consider the following when you are constructing your title:

Same (tileId, tileGroupPath) pair - should have the same tileTitle - as this is THE title of your content node when it appears under that structure point tileGroupPath describes.
Keep it short and simple! Don't just reuse the string you put into <head>/<title>! Remove all prefix/postfix typically added due to SEO purposes is strongly advised.
Remain close to content editors as much as possible! If your CMS distinguishes content internal name/title from the public one then go with the internal one here!
Avoid translations! If your site is multi-lingual make sure you still put the same string here regardless the active language. See the 1^st bullet! Maybe the previous bullet also helps?

It is good to know that if Keytiles detects the title of your (tileId, tileGroupPath) is switching rapidly back and forth (by violating the "same (tileId, tileGroupPath) - should have same tileTitle" principle) then it will raise a warning in the error reports. So by checking the error reports regularly you can detect faulty contents or systematic problems at this place.

tileUrl

default / fallback value: the URL provided by the location.href attribute
type: string
max length: no strict limit for this
possible values: any (free text)

The URL of your content this Tile represents - when it appears under the structural point described by the tileGroupPath tag

tileLabelsJSON

default / fallback value: -
type: string
max length: 512 characters
possible values: must be a valid JSON String encoding a JSON Object.

You have the possibility to store a limited amount of labels - key-value pairs - with Tiles. You get them back via the query result if you do so.

The JSON string must encode a JSON Object - you can put inside this Object whatever you want / need.

For example if you send in tileLabelsJSON = {"myKey1": "myStringValue", "myKey2": 8, "myKey3": true} then this will create labels myKey1, myKey2 and myKey3 on the Tile with the corresponding values.

If you

Persisted labels to a Tile earlier and if you do not send this hit attribute or you send empty string / null value - then it will be simply skipped and the earlier persisted labels remaining unchanged.
If you send an invalid or too long JSON string Keytiles will simply skip what you have sent from the processing (and raising a warning in Fault Reports you can see later) just like you have not sent this value. This leads back to the previous case - there will be no changes in the earlier persisted labels.
If you want to delete / remove all labels simply send an empty object: tileLabelsJSON = {}

Please note that:

The incoming JSON is always used as it is - it will completely replace the Tile labels earlier version if there was any.
This value belongs to the Tile itself - regardless the tileGroupPath tag you use. So make sure you consistently send the same JSON on all your pages into Keytiles.

visitorType

default / fallback value: none
type: string
max length: no strict limit for this
possible values: any (free text)

You can specify the type of the visitor who is currently interacting with the page in the meta tag.

If you want to distinguish - let's say - "free" visitors generated traffic from "paid" visitors then this is the place you can do this by providing visitor type.

It's up to you how you want to call and how many different visitor types you want to distinguish.

primaryTags

default / fallback value: none
type: string (comma separated list)
max length: no strict limit for this - but keep it short as much as possible otherwise can be ugly on UIs ...
possible values: any (free text) - but check the details!

Using this field you can tag the Event (hit) with custom tags. Using these custom tags of yours you can implement your custom segmentation of the traffic generated by your visitors.

For example, if you - for whatever reason - want to assign colors to your website contents (like "red", "blue", "yellow" etc) then you can send primaryTags=red here.

In this case the eventType this hit carries for your content (identified by tileId) is tagged with "red". Then later when you check the traffic you can limit the query (query a segment) to give you what has happened on "red" colored content. This is something you can do in Query API - just check groupBy and/or primaryTagsOnly possibilities there!

We do recommend to read our article Custom segmentation of traffic to learn a bit more about this and get a better understanding!

note:
You might have realized that actually the attribute name is not primaryTag.
It's plural: primaryTags...
Yes, this means that you can send in multiple tag values and not just one. So maybe a content of yours belongs to "red" and "blue" color at the same time then you can send primaryTags=red,blue. You can use comma separated list of tags here. This is why it is plural.

secondaryTags

default / fallback value: none
type: string (comma separated list)
max length: no strict limit for this - - but keep it short as much as possible otherwise can be ugly on UIs ...
possible values: any (free text) - but check the details!

If you need not just coloring we mentioned as a quick example in primaryTags attribute (please check that!) but another segmentation criteria then you can use this attribute too to implement that.

Technically it works the same way as primaryTags attribute.

campaignName

default / fallback value: If there is utm_campaign parameter present in tileUrl attribute then this is automatically recognized and used
type: string
max length: no strict limit for this - but keep it short as much as possible otherwise can be ugly on UIs ...
possible values: any (free text)

If the visitor arrived to your website from a campaign you can indicate this fact in this attribute by providing the name of the Campaign here.

note: Campaign tracking of Keytiles is inspired by UTM parameters concept. This value is conceptually the same as utm_campaign parameter.

campaignMedium

default / fallback value: If there is utm_medium parameter present in tileUrl attribute then this is automatically recognized and used
type: string
max length: no strict limit for this
possible values: any (free text)

If the visitor arrived to your website from a campaign with this attribute you can specify the medium the visitor came from in this Campaign. E.g. "email" if your Campaign is e.g. a newsletter.

note: Campaign tracking of Keytiles is inspired by UTM parameters concept. This value is conceptually the same as utm_medium parameter.

campaignContent

default / fallback value: If there is utm_content parameter present in tileUrl attribute then this is automatically recognized and used
type: string
max length: no strict limit for this - - but keep it short as much as possible otherwise can be ugly on UIs ...
possible values: any (free text)

If the visitor arrived to your website from a campaign using a specific content somewhere like "I'm interested" button or "Recommendation box" somewhere you can mark that as content which has triggered this campaign visit.

note: Campaign tracking of Keytiles is inspired by UTM parameters concept. This value is conceptually the same as utm_content parameter.

Example use-cases for attribute values

Hopefully the following examples will help you to understand better what you should put into the different <meta> tags in different cases

A sample website

Please meet with https://newsportal.com - a fictional website who

has a content structure like this below
this site is CMS backed site - the values in parenthesis are the entity ID of the content in the CMS.
the CMS supports /entity/<entityId> URIs for every content - regardless what is the "nice url" alias
in the /politics area the CMS is going with date-grouping-based technique - so the URLs of articles under /politics are tricky

The site menu                      CMS - entityId               URI of the content
--------------------------------------------------------------------------------------------------------
▪ Home                             ("home")                     /
▪ Politics                         ("page_politics")            /politics
    ▪ Europe                       ("page_politics-europe")     /politics/europe
        - eu article 1             ("f57dac9a-a883")            /2020-11-05/politics/europe/eu-article-1
        - eu article 2             ("9d6a0bb2-f297")            /2020-11-07/politics/europe/eu-article-2
          ...
    ▪ Asia                         ("page_politics-asia")       /entity/page_politics-asia
        - asia article 1           ("8a8371d0-05a0")            /2020-11-05/politics/asia/asia-article-1
        - asia article 2           ("d184681c-2afa")            /entity/d184681c-2afa
          ...
▪ Tech                             ("page_tech")                /tech
    ▪ Smartphones                  ("page_smartphones")         /tech/smartphones
        - smartphone article 1     ("adbaed24-af3a")            /tech/smartphones/smartphone-article-1
        - smartphone article 2     ("a31d3f91-8681")            /tech/smartphones/smartphone-article-2
          ...

and last but absolutely not least

there is a special selection of articles from the full website on the page, named "Interesting"

▪ "Interesting"
    - asia article 2               ("d184681c-2afa")            /what-is-interesting/d184681c-2afa-asia-article-2
    - smartphone article 2         ("a31d3f91-8681")            /what-is-interesting/a31d3f91-8681-smartphone-article-2

Simple use-cases

https://newsportal.com

Visitor is on the "Home" page now. Simple situation. In this case you should return:

{
	"tileId": "home",
	"tileType": "frontpage",
	"tileGroupPath": "/",
	"tileTitle": "Home",
	"tileUrl": "https://newsportal.com"
}

https://newsportal.com/politics

Visitor has clicked to the "politics" menu. And now he is on the "Politics" page, seeing a selection of different political articles from Europe, Asia, etc.
In this case you should simply return:

{
	"tileId": "page_politics",
	"tileType": "page",
	"tileGroupPath": "/politics",
	"tileTitle": "Politics",
	"tileUrl": "https://newsportal.com/politics"
}

https://newsportal.com/tech/smartphones/smartphone-article-1

Visitor is now reading a Tech article: "smartphone article 1". There is no real difficulty here, everything is pretty straightforward.

This example has something interesting, you can learn something here. Focus on tileUrl below!

In this case you could simply return:

{
	"tileId": "adbaed24-af3a",
	"tileType": "article",
	"tileGroupPath": "/tech/smartphones",
	"tileTitle": "Smartphone article 1",

	// let's learn something here! Of course you can return this as tileUrl
	"tileUrl": "https://newsportal.com/tech/smartphones/smartphone-article-1",
	
	// BUT: since our CMS supports entityId based links too
	//      and for Keytiles the tileUrl is not that important
	//      you could also return this - equally fine for Keytiles!
	"tileUrl": "https://newsportal.com/entity/adbaed24-af3a"
}

Tricky use-cases

https://newsportal.com/entity/d184681c-2afa

Here the difficulty is that for whatever reason in our CMS we have lost the "nice url" alias, so the URL does not reflect any structure any longer.

In reality the visitor is reading the "asia article 2" political article - which actually belongs to "/politics/asia" in the structure.

{
	"tileId": "d184681c-2afa",
	"tileType": "article",
	// we can put the article into its correct place in the structure here
	"tileGroupPath": "/politics/asia",
	"tileTitle": "asia article 1",
	// and for simplicity now let's go with the entityId based url here
	"tileUrl": "https://newsportal.com/entity/d184681c-2afa"
}

Same content - but approached from different places

We have a very interesting use-case which is actually often happening on websites.

Please take a look on article "smartphone article 2" - entityId "a31d3f91-8681". What is special in this article is that actually the visitor can get to this article 2 different ways:

In one hand - through the menu. In which case the article belongs to "/tech/smartphones" in the structure
While on the other hand - through the "Interesting" selection - and in this case the article belongs to "/interesting" in the structure

To make the example complete let's assume that

this article received 146 hits through the menu - when it belongs to "/tech/smartphones"
and received 34 hits through the "Interesting" section - when it belongs to "/interesting" in the structure

So what to do with this?

Actually the choice is yours! You need to decide how would you like to see this article in the view. You have two options:

Option 1 - Content stays at main location

If we would go with this option then basically it would mean, that we give up displaying the "/Interesting" as a group in the TileView. It would not appear as category and you would get something like this:

Option 2 - Content shows both places

If we would go with this option then the "/Interesting" as a group would appear on the TileView as category, and the article would show up in both places - showing the number of hits it received through "/tech" and also through "/Interesting" as category

If you want to go with Option 1

then you need this for both URLs

https://newsportal.com/tech/smartphones/smartphone-article-2 and
https://newsportal.com/what-is-interesting/a31d3f91-8681-smartphone-article-2

{
	"tileId": "a31d3f91-8681",
	"tileType": "article",
	// the key is this point
	"tileGroupPath": "/tech/smartphones",
	"tileTitle": "smartphone article 2",
	"tileUrl": "https://newsportal.com/entity/a31d3f91-8681"
}

But if you want to go with Option 2

then for URL https://newsportal.com/tech/smartphones/smartphone-article-2 you need this:

{
	"tileId": "a31d3f91-8681",
	"tileType": "article",
	// the key is this point
	"tileGroupPath": "/tech/smartphones",
	"tileTitle": "smartphone article 2",
	"tileUrl": "https://newsportal.com/entity/a31d3f91-8681"
}

and for URL https://newsportal.com/what-is-interesting/a31d3f91-8681-smartphone-article-2 you need this

{
	"tileId": "a31d3f91-8681",
	"tileType": "article",
	// the key is this point
	"tileGroupPath": "/interesting",
	"tileTitle": "smartphone article 2",
	"tileUrl": "https://newsportal.com/entity/a31d3f91-8681"
}