Data Collection
Initialization
Section titled InitializationThe way our SDK works is by auto-starting with the application launch and attaching to the current process in order to intercept the events and gestures we are interested in.
See Session Replay Initialization to learn how Session Replay is initialized.
Configuration
Section titled ConfigurationOnce started, our SDK fetches it configuration from our servers. Then depending on the segmentation size (defined by our team when you sign a contract) and the user consent status, it will start collecting analytics data from system and user events it detects from the runtime.
Data collection
Section titled Data collectionAnalytics data collection
Section titled Analytics data collectionThe SDK monitors the application, lifecycle events, the view hierarchy, and generates data from the behavior of the app, the content of the screen and the user interactions. These events are then locally stored, and eventually sent to our servers in batches. We then aggregate that data to create usable visual information into our Web Application, which you use to gather insights.
Session Replay data collection
Section titled Session Replay data collectionSee Session Replay Initialization to learn how Session Replay data collection works.
Sending data
Section titled Sending dataSending analytics data
Section titled Sending analytics dataAnalytics data are sent in batches of maximum 50 events. Requests are triggered when network conditions allow for the server to be reached and:
- The current batch of events has reached 50
- Or the app is put in background
Sending Session Replay Data
Section titled Sending Session Replay DataSee Session Replay Requests to learn more about how Session Replay data is sent.
Sending crash Data
Section titled Sending crash DataSee Send Crash data to learn more about how crash data is sent.
Session definition
Section titled Session definitionA session represents a single period of user interaction in the app.
In Contentsquare, the SDK marks the start of a session when an app start
or app show
event is first detected.
A session ends 30 minutes after the last event. This is the default value which be changed upon request.
If the app is put in the background or killed (intentionally by the user or by the OS) and the user comes back within the next 30 minutes, subsequent events are considered part of the same session.
Collected data points
Section titled Collected data points- The events are in JSON format, which lists the properties and their description in comment.
- Events are sent to the server in batches.
- A batch is a subset of events originating from one session. A session can send events in more than one batch.
- The batch size is defined in a run configuration file specific to each app (50 events by default).
Requests meta data
Section titled Requests meta dataEach batch has a common header, a set of device specific, and repeatable information and an array of events, which is immutable. The header is composed at the moment of sending, so it has to be constant info ONLY. The array in the payload is data stored at the moment of collection.
The structure of the batches of events will have the following format:
{ pid:8, // int - ProjectId - represented in the mobile config format uid:"ac1529a7-59f6-49d9-b254-6f0a22f57284", // String - uuid Unique user ID dt:4, // int - device type (loosely enforced enum - [sdk-phone : 4, sdk-tablet :5]) dma:"Samsung", // String - device manufacturer. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. dmo:"SG", // String - device model. This property is optional and if by any chance the device model cannot be determined it will be dropped from the Json object. os:"10.0", // String - os version (Android version name 8.0, 9.0, 10.0) l:"en_US", // String - Language in iso-639 format https://www.ibabbleon.com/iOS-Language-Codes-ISO-639.html tz:"Europe/Paris", // String - timezone https://en.wikipedia.org/wiki/List_of_tz_database_time_zones now:1522159618000, // long - timestamp when the batch was sent to:{ // object - type origin of the event an:"appname" // String - application name st:"sdk-android", // String - type of sdk sf:"release", // string - sdk flavor/variant [release/debug/god] }, r:{ // Device - resolution. w:1080, // int - width h:1920 // int - height d: 1.5 // The device density as float. Its values can vary between (0.75 and 10) }, pl:[] // JSON array payload - list of event objects, see below}
Events meta data
Section titled Events meta dataAll events have a common first part (don’t confuse it with the header explained above). This common section is data which is common for all events by type but is gathered at the moment the event occurred. This common section is a part of the actual event payload.
{ upt:1522, // long - system update in milliseconds euid:"euid", // String - event UUID url:"app-and://identifier/mainPath/secondaryPath?title=screeName", // String - screenName is passed in the title query Parameter scn:4, // int - the number of screens already shown in the session c:3, // int - connectivity type [-1 - offline, 0 - error, 1 - wifi, 2 - 2g, 3 - 3g, 4 - 4g] ci:"verizon", // String - carrier_id when user is on mobile network o:1, // int - orientation [0 = portrait, 1 = landscape] vo:{ // object - version origin of the event sv:"2.1", // string version of the sdk sb:4, // int - sdk build number av:"appVersion", // String - application version af:"appFlavor" // String - application string - [release/debug/god] ab:1 // int - application build number }, sn:1, // int - session id (positive int) t:12894726459435 // long - timestamp of the event (in milliseconds)}
All event specific properties are appended to this JSON object.
App Start
Section titled App StartThis event describes the absolute start of the app.
The trigger for this event is the absolute start of the app.
This is the first event sent when the SDK is invoked.
ea: 0; // int - event action - defined above
App Show
Section titled App ShowThis event is sent when the user brings the app in the foreground (switching from another app, exiting lock screen, etc.). This event means the app is focused.
ea: 1; // int - event action - defined above
App Hide
Section titled App HideThis event is sent when the user exits (minimizes) the app, or switches to something else. This event means the app is not focused and the session might end, but we have not completely ended the session yet, as the user might return.
ea: 2; // int - event action - defined above
Screenview
Section titled ScreenviewEverything starts with a View event. This is an event which describes the equivalent of a “page view” on the web. This event is sent when the Track Screen API is called.
ea:4 // int - event action - defined abovest:"title", // String - screen titlesl:34543 // int - (load time) screen load time (diff between last action and this event)
Single Finger gesture event, when the user is interacting with a loaded screen. This is an event which describes the equivalent of a “click” in the web. This event is defined by the following sequence of touch events:
- Touch Down -> N x Touch Move -> Touch Up
ea:6 // int - event action - defined abovetvp:"[root]>view#id>view2>", // String - target view pathtvid:"btn_ok", // String - target view idur: true, // boolean - was this a "responsive" touch event (the target view had a handler)
Long press
Section titled Long pressSingle Finger gesture event, when the user is interacting with a loaded screen.
This event is defined by the following sequence of touch events:
- Touch Down → N x Touch Move → Touch Up
- Duration: > 500ms
- Distance: < 24 dp
ea:8 // int - event action - defined abovetvp:"[root]>view#id>view2>", // String - target view pathtvid:"btn_ok", // String - target view id
Drag (Slow Swipe)
Section titled Drag (Slow Swipe)Single Finger gesture event, when the user is interacting with a loaded screen.
This event is defined by the following sequence of touch events:
- Touch Down → N x Touch Move → Touch Up
- Distance: > 48 dp
- Finger Velocity < 100 dp/s
ea:9 // int - event action - defined abovetvp:"[root]>view#id>view2>", // String - target view pathtvid:"btn_ok", // String - target view idfd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern]tvd:100, // int - target view distance draggedtvv:100 // int - target view velocity while dragging dp/s
Flick (Fast Swipe)
Section titled Flick (Fast Swipe)Single Finger gesture event, when the user is interacting with a loaded screen.
This event is defined by the following sequence of touch events:
- Touch Down → N x Touch Move → Touch Up
- Distance: > 48 dp
- Finger Velocity > 100 dp/s
ea:10 // int - event action - defined abovetvp:"[root]>view#id>view2>", // String - target view graph pathtvid:"btn_ok", // String - target view idfd: 3, // int - finger direction - [1,2,3,4,5] -> [up, down, left, right, complex_pattern]tvd:100, // int - target view distance scrolledtvv:100 // int - target view velocity while scrolling dp/s
Transaction
Section titled TransactionTo track transactions we provide a public API which can send a transaction object (see section Track Transactions). This object must contain the following parameters:
ea:16, // int - event action - defined abovetr:{ // a json object with different properties defining the transaction made vl: 20.0, // mandatory - float - the value of the transaction cu: 978, // mandatory - int - the ISO 4217 code of the currency of the transaction id: "32akjkljklJ575775" // optional - string - an id for the transaction}
Dynamic variables
Section titled Dynamic variablesTo track dynamic variables we provide a public API (see section Dynamic variables).
ea:18, // int - event action - defined abovek:"key", // String - Custom key assigned by client.v:"value" // String - Custom value assigned by client.
ea:19, // int - event action - defined abovek:"key", // String - Custom key assigned by client.v: 2344 // Integer - Custom value assigned by client.
Exposure Metrics
Section titled Exposure MetricsIn the Zoning Analysis module, Exposure Metrics provide information on the size of the display zone in the application, and data about content exposure in scrolling elements.
Behavior for scrollable elements
Section titled Behavior for scrollable elementsExposure Metrics data for scrolling is only calculated on the first scrollable element on the screen. Other scrolling elements in the view hierarchy are not taken into account.
This event is defined by the following content:
ea:23, // int - event actiondx:10, // int - normalized x content offsetdy:10, // int - normalized y content offsetdu: 5, // int - duration of the movement (in milliseconds)
Exclude ScrollView
, HorizontalScrollView
, NestedScrollView
, or RecyclerView
type object from Exposure Metrics
Section titled Exclude ScrollView, HorizontalScrollView, NestedScrollView, or RecyclerView type object from Exposure MetricsTo exclude a scrollable container from Exposure Metrics, use the Contentsquare.excludeFromExposureMetric(View)
API. Call it from the onCreate
method of the activity or the onCreateView
method of the fragment.
import com.contentsquare.CSQ
public override fun onResume() { super.onResume()
// ... val scrollView = findViewById<ScrollView>(R.id.scrollView) // or HorizontalScrollView, NestedScrollView, or RecyclerView CSQ.excludeFromExposureMetric(scrollView)}
import com.contentsquare.CSQ;
@Overridepublic void onResume() { super.onResume();
// ... ScrollView scrollView = findViewById(R.id.scrollView); // or HorizontalScrollView, NestedScrollView, or RecyclerView CSQ.excludeFromExposureMetric(scrollView);}