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": 1543355710,
	"hitProducer": "string",
	"method": "incremental",
	"value": 1,
	"tileId": "string",
	"tileTitle": "string",
	"tileGroupPath": "/mainTileGroup/subTileGroup",
	"action": "pageview",
	"tileType": "frontpage",
	"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,
	"action": "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",
	"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 - preparing your Container setup

To be able to see the traffic your app is sending in segregated form you will use the "userAgentType" field to identify hits coming from your App!

Let's assume you have

  • an Android app
  • and an iOS app too
  • and we want them to act as two different traffic sources

To prepare Keytiles for this do the following:

  1. Go to our System UI and log in with your account
  2. Go to your Container settings page
  3. In the "Custom user agent type" field create two entries - one for your iOS and another for your Android app, like this:

    custom-user-agent.png
  4. Don't forget to save the changes!
  5. If you did it right then when you open the TileView the two new sources will appear under the Devices, like this:

    devices-list-tileview.png

Step 3 - start sending in hits!

You are ready now! From your iOS and Android Apps start sending in hits into the Hit Collection API!

There is one thing which is important!

From your iOS App make sure you 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 4 - 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!