Sending in traffic from iOS/Android/etc apps

Content of this page

Prerequisite

Before you continue we assume you are already aware of the concept of Hit attributes. If this is not the case then take a look now!

Step 0 - do you have a tracked website too?

If the answer is "yes" and your App is working with (=showing) the same (or partial) content then you should stop for a second and synchronize the Hit attributes

  • your App will generate
  • your website is using

when they are displaying the same content!

Are you using the Keytiles <meta> tags on your website already? Maybe take a quick look into that article before you continue...

Step 1 - our Hit Collection API - at your service!

You want to integrate something with something - so we assume you have seen OpenApi contracts right? No? And how about the word Swagger?

Great! Then first of all click this link and take a look into our Hit Collection API contract! You will see the detailed description of every field there - you can send into Keytiles in a JSON object. Will make sense - more or less... But let us shed some light on some details - keep reading!

.So this is the full object with all fields (at least at the moment we are writing this docs...)

{
	"containerId": "string",
	"sourceTime": null,       // to let server assign
	"hitProducer": "string",
	"method": "incremental",
	"value": 1,
	"tileId": "string",
	"tileTitle": "string",
	"tileGroupPath": "/mainTileGroup/subTileGroup",
	"eventType": "pageview",
	"tileType": "frontpage",
	"tileLanguage": "en",
	"tileUrl": "string",
	"uniqueWebClientId": "string",
	"pseudoUniqueWebClientId": "string",
	"userAgentType": "browser-desktop",
	"referrerUrl": "string",
	"referrerTileId": "string",

	"visitorEnvironment": {
		"resolution": "1920x1080",
		"windowSize": "846x712",
		"windowId": "string",
		"locale": "en-US",
		"opSystem": "string",
		"webClient": "string"
	}
}

It's big, we know. And the purpose of this page eventually will be to let you understand everything much better than now! But we can start a bit easier... Because actually a minimum hit object looks like this:

{
	// JSON does not support comments normally, but our code coloring snippet does :-)
	// so let's use it for now!
	
	// some trivial fields
	"containerId": "<your container id comes here>",
	"sourceTime": <just add the UNIX ts here fetched from the device>,
	
	// simply just fill these up with these values
	"hitProducer": "myApp",
	"method": "incremental",
	"value": 1,
	"eventType": "pageview",	
	
	// Have you checked the "Prerequisite" section above?
	// You need to be familiar with our "Hit attributes" concept!
	"tileId": "tileId hit attribute comes here",
	"tileTitle": "tileTitle hit attribute comes here",
	"tileGroupPath": "tileGroupPath hit attribute comes here",
	"tileType": "tileType hit attribute comes here",
	"tileLanguage": "tileLanguage hit attribute comes here",
	"tileUrl": "tileUrl hit attribute comes here",
	
	// This field is important to recognize returning visitor and also to join clicks into visit sessions!
	// You can leave it on NULL but if you do then every hit will produce "bouncer" visits and we see every
	// hit as a "new" visitor ... better avoid this
	// You are really strongly adviced to find a way to generate some ID here to identify the visitor's
	// device - which will be the same too for every clicks in the future he makes from this device!
	// IMPORTANT! Do NOT use any personal/sensitive data in this field! It is forbidden!
	"uniqueWebClientId": "<unique device id>",
	// you can leave this on NULL as a start
	"pseudoUniqueWebClientId": null,
	
	// OK, this one will be important really! Check the below section(s)!!
	"userAgentType": "<short name/id of your app - the one you added to your Container settings>",
	
	// for now you can leave all of these on NULL
	"referrerUrl": null,
	"referrerTileId": null,
	"visitorEnvironment": null
}

Step 2 - choosing "userAgentType"

There is one hit-attribute which is important at this point: userAgentType This attribute is driving the segregation of your visitor traffic in terms of which client (the "app") was used by your visitor while interacting with your website. You have to choose a short, string based identifier for your agent and then using it consistently. Meaning: you always send this identifier with all events towards Keytiles from the same app.

For example assuming you want to integrate your native iOS and Android readers from your iOS App you could use this:

{
	...

	"userAgentType": "iOS-App",

	...
}

While from your Android App make sure you use this:

{
	...

	"userAgentType": "Android-App",

	...
}

If you did everything right then the traffic will appear in Keytiles nicely.

Step 3 - further polishments

As now you have hits in Keytiles it is time to focus a bit on all of those fields (in the JSON) we elegantly skipped so far! :-)

Like the visitorEnvironment, or the referrerTileId / referrerUrl, things like this. Please read the details of these fields in the Hit Collection API and try to implement as much as possible!