Hit attributes

"hit" is the name of the events Keytiles receives through the Hit Collection API - representing the fact that a visit has happened somewhere in the content. At this point Keytiles needs to know which content got the hit 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. So to put is short:

Attribute reference

tileId

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

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

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

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!

 

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)

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

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

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 "/ /"

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

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.

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

tileTitle

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

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

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 1st 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

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

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)

tileLabelsJSON

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.

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

visitorType

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.

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

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"
}