Hit attributes

"hit" is the name of the event 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.

default / fallback value: "article"
type: enum of strings
possible values: one of "frontpage" | "page" | "article"

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 defining 3 different major types so far which 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 is a "leaf" type in your content tree

The visitor will not 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.

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!

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)

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