NAV Navbar
Logo
code

Introduction

The Deep Media Analytics (DMA) is a part of the Deep.BI platform. It allows to track users’ interactions with web content using JavaScript snippets or REST API.

Deep Media Analytics supports:

Media companies can start analyze their data just after installing the DMA scripts on their websites (usually via CMS) and setting up a few variables or they can use REST API.

The goal of this document is to assist the developer responsible for integration of Deep.BI. This document describes integration with JavaScript, but integration can be done with REST API.

The DMA JavaScript code is fully asynchronous in order to not slow down publisher’s site. Once loaded, DMA code works like most other analytics services — it triggers the loading of a beacon image, which returns a 1x1 pixel image.

Implementation Guide

This guide covers all steps that you need to take in order to fully integrate Deep Media Analytics script with your website.

1. Integrate DMA snippet

This part shouldn’t take more than 5 to 15 minutes of your time. To implement main DMA snippet follow our Quick Start Guide.

2. Prepare Implementation Plan

Before you proceed with integrating custom data we recommend to prepare Implementation Plan based on this template: Implementation Plan Template

Make yourself a copy of that file and list all the custom events and attributes you would like to collect before you proceed with integration of custom data. If you have any questions during this part do not hesitate to contact our Support Team.

3. Custom Attributes Integration

Integrate custom attributes from your Implementation Plan.

Resources:

4. Custom Events Integration

Integrate custom events from your Implementation Plan.

Resources:

Quick Start Guide

Implementation

To implement DMA tracking script, past this code into the head section

<script type="text/javascript">
/* Deep Media Analytics (c) 2016-05-02 v1.2.2 */
!function(){function b(a,b){"function"!=typeof f[a]&&(f[a]=b)}function e(c,d,e,f,a){var b=function(b){i&&i(b);var k=e.push(b),h=g[f];if(h)for(var j=0;j<h.length;++j)h[j](d,b,c[5],k);return a};return a||(a=b),b}function o(d){var c,b=a[j]("script");for(b.type="text/javascript",b.async=!0,b.src="http"+("https:"===a.location.protocol?"s:":":")+d;!(c=a[k](m)[0]);)a[k]("html")[0][l](a[j](m));c[l](b)}var a,n=new Date,h=new Function("return this;")(),d=h.top;try{a=d.document}catch(q){}void 0===a&&(d=h,a=d.document);var f=d.DeepTrack||(d.DeepTrack={}),c={},g={},i=Object.freeze;b("hash",function(a){function hash(){return a}return hash}),b("each",function(d,a){a||(a=1);for(var e in c)for(var f=c[e],h=f[a],i=f[5],b=0;b<h.length;++b)d(e,h[b],i,b);var j=g[a]||(g[a]=[]);j.push(d)}),b("getInitTime",function(){return n}),b("options",function(a){return c[a][0].options}),b("track",function(d,g){var a,h,i,j,k,b=c[d];return b?(a=b[0],g&&(b[5]=g)):(c[d]=b=[0,h=[],i=[],j=[],k=[],g],b[0]=a=e(b,d,h,1),a.event=e(b,d,i,2,a),a.transform=e(b,d,j,3,a),a.newpage=e(b,d,k,4,a),a.hash=f.hash,a.options={}),a});var j="createElement",k="getElementsByTagName",l="appendChild",m="head",p="function"==typeof a.querySelectorAll?"":"-sizzle";o("//api.deep.bi/scripts/v1/track"+p+".js")}();
</script>

Installing DMA JavaScript code should be as easy as pasting this snippet inside the <head> tag, preferably right after the opening.

Most recent version of DMA script is available here: DMA tracking script

Once this script is implemented globally across your site, you might need to make a few configuration tweaks to better fit your site. All of these options are outlined in the rest of this guide.

Authorization

For simplicity in further examples we will set a global variable deep with the initialized tracker. In further examples we will refer to this global variable. However setting the global variable in this way is not required.

<script type="text/javascript">
var deep = DeepTrack.track("YOUR_STREAM_KEY", "YOUR_WRITE_KEY");
</script>

To send data you need to obtain two authorization keys:

You can set a global variable containing your authorization keys or send them every time you send data.

For the first option put an authorization snippet below the main loading script.

Sending Data

Send data by referring to the global tracker variable

<script type="text/javascript">deep();</script>

Alternative: authorize and send data without setting the global variable

<script type="text/javascript">
DeepTrack.track("YOUR_STREAM_KEY", "YOUR_WRITE_KEY")();
</script>

To start collecting data put the following script in the place where it should be fired.

In most cases it can be anywhere in the <body> section of a page. The script will gather automatically pre-defined type of events - see Events section for more details.

If you’d like to collect custom events with your own parameters you should add custom lines of the script in a place where these events occur. For more details see our Advanced Integration Guide.

Testing Integration

In order to make sure you have completed this steps successfully you should test your integration. To do that you can use developer tools in your web browser. See below short description how to do it in most popular ones. Although the process is very similar for each one of them.

Chrome, Opera

  1. Open Developer Tools in your browser.
    chrome_dev_tools

  2. Got Network tab and select XHR on the filter tab.

  3. Click on the request named events.

  4. In Headers your Request URL should look like this: http://api.deep.bi/v1/streams//events, where is replaced by your actual key, Your status code should be 204.

  5. Scroll down to Request Payloads and expand specific event attributes. Check their values to confirm your integration.
    request_headers

Firefox

  1. Go to Menu -> Developer -> Network.
  2. On the bottom of the Developer Console you should see bar with filters, click XHR.
  3. Choose events request on the list.
  4. On your right another window should appear. Go to Params tab to see all the data that is send from your website to Deep.BI.

Edge

  1. Open Developer Tools (F12).
  2. Go to Network tab.
  3. Filter out XHR elements.
  4. Choose events request on the list.
  5. In the window on the right choose the content (second) tab and then, choose request content to see data send to Deep.BI in a json.

Events

Various events are sent when handling media that are embedded in HTML documents using the <audio> and <video> elements; this section lists them and provides some helpful information about using them. Moreover, DMA collect automatically web events like opening a page, page load time, page bounce etc.

Website Events

Event Type Description
page-open User opened a page
page-ping Page-ping event is sent after each 15 seconds of user activity. Each event in user session has its number in sequence, starting from 1 (dimension: pingSeq). That means that DMA customers can easily and flexibly define custom event like Page View 30s+ with pingSeq = 2.

Media Events (Audio & Video)

Media companies can use the HTML <video> element to embed video content in a document. The video element contains one or more video sources. To specify a video source, use either the src attribute or the <source> element; the browser will choose the most suitable one.

The HTML <audio> element is used to embed sound content in documents. It may contain one or more audio sources, represented using the src attribute or the <source> element; the browser will choose the most suitable one.

To enable collecting media events specify

deep.options.media = true

One may control which media are tracked specifying the css selector of the desired HTML video or audio tags.

To watch only <video class="ad-one" > tags specify

deep.options.media = "video.ad-one"

Multiple selectors are possible

deep.options.media = ["video", "audio#my_audio"]

Furthermore it’s possible to specify which events are tracked for specified selectors.

To collect the default events for the <video> tags and only the specified events: playing, pause and progress for <video id="my_audio" > tag specify

deep.options.media = [
  "video",
  {
    select: "audio#my_audio",
    events: "playing pause progress"
  }]

Below you’ll see the list of events that are gathered automatically by DMA script if media tracking is enabled. You will see in your data “audio” or “video” prefix accordingly, depending of the media event type.

For example, instead of [media]-play, we will capture audio-play or video-play event.

Event Type Description
[media]-abort Sent when playback is aborted; for example, if the media is playing and is restarted from the beginning, this event is sent.
[media]-ended Sent when playback completes.
[media]-error Sent when an error occurs. The element’s error attribute contains more information. See Error handling for details.
[media]-playing Sent when the media begins to play (either for the first time, after having been paused, or after ending and then restarting).
[media]-pause Sent when playback is paused.
[media]-seeked Sent when a seek operation completes.
[media]-waiting Sent when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek).

Below are the events that may also be captured by specifying them explicitely.

To select which events are captured specify

deep.options.media = {
  events: "playing error pause progress volumechange"}

To select which events are captured for selected tags specify

deep.options.media = {
  select: "video.media-to-track",
  events: "playing error pause progress volumechange"}

Be carefull though, enabling some of the events below may generate a lot of tracking traffic, mainly: progress, seeking, suspend or stalled.

Event Type Description
[media]-canplay Sent when enough data is available that the media can be played, at least for a couple of frames. This corresponds to the HAVE_ENOUGH_DATA readyState.
[media]-canplaythrough Sent when the ready state changes to CAN_PLAY_THROUGH, indicating that the entire media can be played without interruption, assuming the download rate remains at least at the current level. Note: Manually setting thecurrentTime will eventually fire a canplaythrough event in firefox. Other browsers might not fire this event.
[media]-durationchange The metadata has loaded or changed, indicating a change in duration of the media. This is sent, for example, when the media has loaded enough that the duration is known.
[media]-emptied The media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the load() method is called to reload it.
[media]-encrypted The user agent has encountered initialization data in the media data.
[media]-interruptbegin Sent when audio playing on a Firefox OS device is interrupted, either because the app playing the audio is sent to the background, or audio in a higher priority audio channel begins to play. See Using the AudioChannels API for more details.
[media]-interruptend Sent when previously interrupted audio on a Firefox OS device commences playing again — when the interruption ends. This is when the associated app comes back to the foreground, or when the higher priority audio finished playing. See Using the AudioChannels API for more details.
[media]-loadeddata The first frame of the media has finished loading.
[media]-loadedmetadata The media’s metadata has finished loading; all attributes now contain as much useful information as they’re going to.
[media]-loadstart Sent when loading of the media begins.
[media]-mozaudioavailable Sent when an audio buffer is provided to the audio layer for processing; the buffer contains raw audio samples that may or may not already have been played by the time you receive the event.
[media]-play Sent when playback of the media starts after having been paused; that is, when playback is resumed after a prior pause event.
[media]-progress Sent periodically to inform interested parties of progress downloading the media. Information about the current amount of the media that has been downloaded is available in the media element’s buffered attribute.
[media]-ratechange Sent when the playback speed changes.
[media]-seeking Sent when a seek operation begins.
[media]-stalled Sent when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
[media]-suspend Sent when loading of the media is suspended; this may happen either because the download has completed or because it has been paused for any other reason.
[media]-timeupdate The time indicated by the element’s currentTime attribute has changed.
[media]-volumechange Sent when the audio volume changes (both when the volume is set and when the muted attribute is changed).

Performance Events

This section describes events that measure load time of page resources such as images, css style sheets or external scripts.

To track load time of resources specify

deep.options.performance = true

Measure only scripts and images

deep.options.performance = ["script", "img"]

Measure only stylesheets by selecting all files that ends with .css

deep.options.performance = /.*\.css$/;

If you want to control which resources are being measured you may specify them with string or regular expression patters.

Performance event types

Event Type Description
resource-performance Measure of the resource loading time

Performance event attributes

Variable name Description
resource.name Resource URL
resource.type Element name that initiated resource loading. E.g.: `link`, `script`, `img`, `css` or `xmlhttprequest`
resource.starttime A timestamp in milliseconds immediately before the browser starts to fetch the resource relative to the beginning of page loading.
resource.duration Milliseconds of the duration of the performance event.
resource.endtime startTime + duration. A timestamp relative to the beginning of page loading.

Error Events

Implementation

To implement DMA tracking script include the special version of the initial code into the head section.

Special head snippet with error tracking enabled

<script type="text/javascript">
/* Deep Media Analytics (c) 2016-05-02 v1.2.2 */
!function(){function d(a,b){"function"!=typeof c[a]&&(c[a]=b)}function f(c,d,e,f,a){var b=function(b){h&&h(b);var k=e.push(b),i=g[f];if(i)for(var j=0;j<i.length;++j)i[j](d,b,c[5],k);return a};return a||(a=b),b}function o(d){var c,b=a[m]("script");for(b.type="text/javascript",b.async=!0,b.src="http"+("https:"===a.location.protocol?"s:":":")+d;!(c=a[l](k)[0]);)a[l]("html")[0][j](a[m](k));c[j](b)}var a,n=new Date,i=new Function("return this;")(),b=i.top;try{a=b.document}catch(q){}void 0===a&&(b=i,a=b.document);var c=b.DeepTrack||(b.DeepTrack={}),e={},g={},h=Object.freeze;d("hash",function(a){function hash(){return a}return hash}),d("each",function(c,a){a||(a=1);for(var d in e)for(var f=e[d],h=f[a],i=f[5],b=0;b<h.length;++b)c(d,h[b],i,b);var j=g[a]||(g[a]=[]);j.push(c)}),d("getInitTime",function(){return n}),d("options",function(a){return e[a][0].options}),d("track",function(d,g){var a,h,i,j,k,b=e[d];return b?(a=b[0],g&&(b[5]=g)):(e[d]=b=[0,h=[],i=[],j=[],k=[],g],b[0]=a=f(b,d,h,1),a.event=f(b,d,i,2,a),a.transform=f(b,d,j,3,a),a.newpage=f(b,d,k,4,a),a.hash=c.hash,a.options={}),a});var m="createElement",l="getElementsByTagName",j="appendChild",k="head",p="function"==typeof a.querySelectorAll?"":"-sizzle";o("//api.deep.bi/scripts/v1/track"+p+".js"),c.errors=[],b.addEventListener("error",function(a){c.errors.push([new Date,a])},!0)}();
</script>

To enable tracking errors specify

deep.options.errors = true

Error event types

Event Type Description
page-error A javascript, resource or an AJAX HTTP error.

Error event attributes

Variable name Description
error.colno A javascript error column number.
error.filename A javascript error document filename.
error.lineno A javascript error line number
error.message Error message
error.responseURL Ajax response url of the HTTP error.
error.status Ajax response status code of the HTTP error
error.target.nodeName HTML element name causing a resource error
error.target.src <img> or <script> source causing a resource error
error.target.href <link> url causing a resource error

Data Attributes

All collected events will be automatically enriched by a whole set of additional dimensions in the following areas:

Event Context

event.type

Type of event - see chapter 3 (e.g. video_play)

event.timestamp

Timestamp of the event

event.pingseq

Sequence number of page ping event. This is a technical parameter that is used for track detailed active user engagement (Attention Time Spent) in accordance to the public Chartbeat methodology.

Time Context

event.localtime.year

Year, e.g. 2016

event.localtime.month

Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec

event.localtime.monthno

Number of the month: 1, 2, … 12, where 1 is January, 12 is December

event.localtime.day

Day of the month: 1, 2, … [28 | 29 | 30 | 31]

event.localtime.hour

Hour of the day: 0, 1, 2, … 23

event.localtime.minute

Minute of the hour: 0, 1, 2, … 59

event.localtime.weekday

Sun, Mon, Tue, Wed, Thu, Fri, Sat

event.localtime.weekdayno

0, 1, … 6, where 0 is Sunday, and 6 is Saturday

event.localtime.utcoffset

Local timezone offset in minutes from UTC.

Page Context

To better explain page context data we use an example page from NY Times page:

For this URL, DMA script registers the following attributes:

page.protocol="http"
page.host="www.nytimes.com"
page.hostname="www.nytimes.com"
page.port=""
page.path="/video/movies/100000004142315/anatomy-of-a-scene-the-revenant.html"
page.href="http://www.nytimes.com/video/movies/100000004142315/anatomy-of-a-scene-the-revenant.html"
page.search="?playlistId=1194811622182&region=video-grid&version=video-grid-thumbnail&contentCollection=Times+Video&contentPlacement=6&module=recent-videos&action=click&pgType=Multimedia&eventName=video-grid-click"
page.query.playlistId="1194811622182"
page.query.region="video-grid"
page.query.version="video-grid-thumbnail"
page.query.contentCollection="Times+Video"
page.query.contentPlacement="6"
page.query.module="recent-videos"
page.query.action="click"
page.query.pgType="Multimedia"
page.query.eventName="video-grid-click"
page.hash="section-btf"

http://www.nytimes.com/video/movies/100000004142315/anatomy-of-a-scene-the-revenant.html?playlistId=1194811622182&region=video-grid&version=video-grid-thumbnail&contentCollection=Times+Video&contentPlacement=6&module=recent-videos&action=click&pgType=Multimedia&eventName=video-grid-click#section-btf

Page context characterizes the place on the web where users are browsing an article, watching a video and where they came from.

There are two high level groups of parameters: page and referrer.

Page is a web page (URL) where the video was loaded from.

Referrer is a URL of a web page that a user had visited before he or she came to the page.

page.domain

This should be set explicitly by client’s script.

page.title

HTML head title of the page

page.protocol

Usually http or https

page.host

Domain with page.port e.g. www.nytimes.com:8222

page.hostname

Domain, e.g. www.nytimes.com

page.port

HTTP protocol port. When a page use the default http port 80, the field is empty.

page.path

Part of the URL, excluding page.protcol, page.host, page.search and page.hash

page.href

URL of the page

page.search

Parameter string in the URL starting after “?” character

page.query.[parameter]

Parsed search parameter (see above) where [parameter] is the parameter name. For example URL: `http://deep.bi/?utm_source=google&utm_medium=cpc` generates `page.query.utm_source=“google”` `page.query.utm_medium=“cpc”`

page.hash

Parameter string in the URL starting after “#” character

page.loadtime

Time to load the page in milliseconds (page-open events only)

referrer.protocol

Usually http or https

referrer.host

URL with page.port e.g. www.nytimes.com:8222

referrer.hostname

URL of the referrer without protocol, port and path, e.g. www.nytimes.com, m.facebook.com

referrer.domain

Domain, e.g. nytimes.com, facebook.com

referrer.port

HTTP protocol port. When a page use the default http port 80, the field is empty.

referrer.path

Part of the URL, excluding page.protocol, page.host, page.search and page.hash

referrer.href

URL of the referrer page

referrer.search

Parameter string in the URL starting after “?” character

referrer.query.[parameter]

Parsed search parameter (see above) where [parameter] is the parameter name. For example URL: `http://deep.bi/?utm_source=google&utm_medium=cpc` generates `referrer.query.utm_source=“google”` `referrer.query.utm_medium=“cpc”`

referrer.hash

Parameter string in the URL starting after “#” character

Video or Audio Context

DMA script collects all available audio or video attributes when an event occurs. In the table below we list those attributes. In data loaded to DMA the [media] will be replaced by video or audio accordingly. If an attribute is present with one kind of events only (audio or video) we put that in the table.

[media].autoplay

A Boolean attribute; if specified, the video automatically begins to play back as soon as it can do so without stopping to finish loading the data.Note: Some versions of Chrome only acknowledge autostart, rather than autoplay

[media].controls

If this attribute is present, the browser will offer controls to allow the user to control video playback, including volume, seeking, and pause/resume playback.

[media].currentsrc

The absolute URL of the chosen media resource.

[media].currenttime

The current playback time in seconds.

video.crossorigin

This enumerated attribute indicates whether to use CORS to fetch the related image. CORS-enabled resources can be reused in the canvas element without being tainted. The allowed values are:
anonymous
Sends a cross-origin request without a credential. In other words, it sends the Origin: HTTP header without a cookie, X.509 certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (by not setting the Access-Control-Allow-Origin: HTTP header), the image will betainted, and its usage restricted.
use-credentials
Sends a cross-origin request with a credential. In other words, it sends the Origin: HTTP header with a cookie, a certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (throughAccess-Control-Allow-Credentials: HTTP header), the image will be tainted and its usage restricted.

When not present, the resource is fetched without a CORS request (i.e. without sending the Origin: HTTP header), preventing its non-tainted used in canvas elements. If invalid, it is handled as if the enumerated keyword anonymous was used. See CORS settings attributes for additional information.

[media].defaultmuted

The muted HTML attribute, which indicates whether the media element’s audio output should be muted by default.

[media].defaultplaybackrate

The default playback rate for the media.

[media].duration

The length of the media in seconds, or 0 if no media data is available.

[media].ended

Whether the media element has finished playing.

[media].error

The most recent error, or null if there has not been an error.

video.height

The height of the video’s display area, in CSS pixels.

[media].id

The id attribute of the media HTML element if specified.

[media].loop

A Boolean attribute; if specified, we will, upon reaching the end of the video, automatically seek back to the start.

[media].mediagroup

The name of the group of elements it belongs to. A group of media elements shares a common MediaController.

[media].muted

A Boolean attribute which indicates the default setting of the audio contained in the video. If set, the audio will be initially silenced. Its default value is false, meaning that the audio will be played when the video is played.

[media].playbackrate

The rate at which the media is being played back.

[media].paused

Whether the media element is paused.

[media].preload

This enumerated attribute is intended to provide a hint to the browser about what the author thinks will lead to the best user experience. It may have one of the following values:
none: indicates that the video should not be preloaded.
metadata: indicates that only video metadata (e.g. length) is fetched.
auto: indicates that the whole video file could be downloaded, even if the user is not expected to use it.
the empty string: synonym of the auto value.
If not set, its default value is browser-defined (i.e. each browser may have its default value). The spec advises it to be set to metadata.

Usage notes:
The autoplay attribute has precedence over preload. If autoplay is specified, the browser would obviously need to start downloading the video for playback. The specification does not force the browser to follow the value of this attribute; it is a mere hint.

video.poster

A URL indicating a poster frame to show until the user plays or seeks. If this attribute isn’t specified, nothing is displayed until the first frame is available; then the first frame is shown as the poster frame.

[media].seeking

Whether the media is in the process of seeking to a new position.

[media].src

The URL (or URLS) of the media to embed.

[media].sources.N.src

The N'th URL of the media source embed in the <source> tag.

[media].sources.N.type

The N'th mime type of the media source embed in the <source> tag.

video.width

The width of the video’s display area, in CSS pixels.

[media].volume

The playback volume, in the range 0.0 (silent) to 1.0 (loudest).

video.videoheight

The intrinsic height of the resource in CSS pixels, taking into account the dimensions, aspect ratio, clean aperture, resolution, and so forth, as defined for the format used by the resource.

video.videowidth

The intrinsic width of the resource in CSS pixels, taking into account the dimensions, aspect ratio, clean aperture, resolution, and so forth, as defined for the format used by the resource.

Iframe Context

iframe.protocol

Usually http or https

iframe.host

Domain with page.port e.g. www.nytimes.com:8222

iframe.hostname

Domain, e.g. www.nytimes.com

iframe.port

HTTP protocol port. When a page use the default http port 80, the field is empty.

iframe.path

Part of the URL, excluding page.protocol, page.host, page.search and page.hash

iframe.href

URL of the page where the video was loaded from, without parameters (page.protocol + page.host + page.path)

iframe.search

Parameter string in the URL starting after “?” character

iframe.hash

Parameter string in the URL starting after “#” character

User ID Context

List of user IDs.

user.id.deepcookie

Cookie that installed by DMA script

user.id.ip

User IP number

user.id.session

Unique session ID used for joining user events within one session

user.id.fingerprint

[available Q3 2016] Unique user ID based of browser fingerprinting.

User Attention Context

User attention characteristics.

user.attention.active

Active time spent on page in milliseconds

user.attention.idle

Idle time spent on page in milliseconds

user.attention.total

Total time spent on page in milliseconds

User Location Context

User location characterizes physical user location based on user IP address.

user.location.countrylong

Country name based on ISO 3166.

user.location.countryshort

Two-character country code based on ISO 3166.

user.location.region

Region, state, county or province.

user.location.city

City name.

user.location.zipcode

ZIP/Postal code (156 countries supported).

user.location.latitude

Latitude of city.

user.location.longitude

Longitude of city.

user.location.elevation

Average height of city above sea level in meters (m).

user.location.timezone

UTC time zone (with DST supported).

user.location.iddcode

The IDD prefix to call the city from another country.

user.location.areacode

A varying length number assigned to geographic areas for call between cities (175 countries supported).

User Internet Provider

This context describes the internet provider a user is using during the web event.

user.location.isp.name

Name of internet service provider

user.location.isp.domain

Internet domain name associated to IP address range.

user.location.isp.usagetype

Usage type classification of ISP or company:
  • (COM) Commercial
  • (ORG) Organization
  • (GOV) Government
  • (MIL) Military
  • (EDU) University/College/School
  • (LIB) Library
  • (CDN) Content Delivery Network
  • (ISP) Fixed Line ISP
  • (MOB) Mobile ISP
  • (DCH) Data Center/Web Hosting/Transit
  • (SES) Search Engine Spider
  • (RSV) Reserved

user.location.isp.mobile.brand

Commercial brand associated with the mobile carrier.

user.location.mobile.countrycode

Mobile Country Codes (MCC) as defined in ITU E.212 for use in identifying mobile stations in wireless telephone networks, particularly GSM and UMTS networks.

user.location.mobile.networkcode

Mobile Network Code (MNC) is used in combination with a Mobile Country Code (MCC) to uniquely identify a mobile phone operator or carrier.

user.location.isp.netspeed

Internet connection type.
DIAL = dial up, DSL = broadband/cable/fiber, COMP = company/T1

User Weather Context

The current version of weather enrichment provides weather station information and allows to further enrich it with weather data.

user.location.weather.weatherstation.code

The special code to identify the nearest weather observation station.

user.location.weather.weatherstation.name

The name of the nearest weather observation station.

User Device Context

User device context describes characteristics of the device a user is using.

Hardware - device type

user.device.hardwareplatform.device.devicetype

Indicates the type of the device based on values set in other properties, such as IsMobile, IsTablet, IsSmartphone, IsSmallScreen etc. Note that if the device runs on a smart operating system such as Android, Windows Phone etc. but the screen size is less than 2.5 inches, the ‘DeviceType’ property returns 'SmallScreen’.

user.device.hardwareplatform.device.isconsole

Indicates if the device is primarily a game console, such as Xbox or Playstation.

user.device.hardwareplatform.device.isereader

Indicates if the device is primarily advertised as an e-reader. If the device type is EReader then the device is not classified as a tablet.

user.device.hardwareplatform.device.ismediahub

Indicates if the device is a media hub or set top box that requires an external display(s).

user.device.hardwareplatform.device.ismobile

Indicates if the device’s primary data connection is wireless and the device is designed to operate mostly by battery power (e.g. mobile phone, smartphone or tablet). This property does not indicate if the device is a mobile phone or not. Laptops are not classified as mobile devices under this definition and so 'IsMobile’ will be 'False’.

user.device.hardwareplatform.device.issmallscreen

Indicates if the device is a mobile with a screen size less than 2.5 inches. If the device does not have a screen then the value 'False’ is returned.

user.device.hardwareplatform.device.issmartphone

Indicates if the device can make and receive phone calls, has a screen size greater than or equal to 2.5 inches and less than 7 inches, runs a modern operating system (Android, iOS, Windows Phone, BlackBerry etc.) and is not designed to be a wearable technology.

user.device.hardwareplatform.device.issmartwatch

Indicates if the device is a computerised wristwatch that enables access to internet and other capabilities beyond timekeeping, such as notifications of incoming calls or texts on a connected smart phone. It runs on a Smart Operating System i.e. Android, WatchOS, Tizen, Ubuntu Touchand is designed to be a wearable technology.

user.device.hardwareplatform.device.istablet

The device is classified as a tablet if the manufacturer sells the device primarily as a tablet, or if the device is primarily advertised as a phablet and has a screen size equal to or greater than 7 inches.

user.device.hardwareplatform.device.istv

Indicates if the device is a TV running on a smart operating system e.g. Android. li#HardwarePlatform_Inputs.category

Hardware - device name

user.device.hardwareplatform.name.hardwarefamily

Refers to the name of devices that only differ by model or region but are marketed under the same name, e.g. Galaxy Tab S 10.5.

user.device.hardwareplatform.name.hardwaremodel

Refers to the model name or number used primarily by the hardware vendor to identify the device, e.g.SM-T805S. This is not always the name the device is most often known by; use HardwareName for a list of popular device names.

user.device.hardwareplatform.name.hardwarename

Refers to a list of marketing names associated with the device, separated by a ’|’. A device may be known by many names depending on region or network, e.g. Huawei Y6.

user.device.hardwareplatform.name.hardwarevendor

Refers to the name of the company that manufactures the device or primarily sells it, e.g. Samsung.

user.device.hardwareplatform.name.oem

Refers to the name of the company that manufactures the device.

Hardware - device release date

user.device.hardwareplatform.date.releasemonth

Refers to the month in which the device was released or the month in which the device was first seen by 51Degrees (if the release date cannot be identified).

user.device.hardwareplatform.date.releaseyear

Refers to the year in which the device was released or the year in which the device was first seen by 51Degrees (if the release date cannot be identified).

Hardware - device features

user.device.hardwareplatform.battery.hasremovablebattery

Indicates if the device has a removable battery. This property is not applicable for devices that do not have batteries. Unless otherwise stated this property will return a 'False’ value for tablets.

user.device.hardwareplatform.camera.has3dcamera

Indicates if the device has a camera capable of taking 3D images. This property will return 'False’ for a device that does not have a camera.

user.device.hardwareplatform.camera.hascamera

Indicates if the device has a camera.

user.device.hardwareplatform.connectivity.hasnfc

Indicates if the device has embedded NFC (Near Field Communication) wireless technology that enables the exchange of data between devices either by touching the devices together or bringing them into a distance of 10 cm or less.

user.device.hardwareplatform.connectivity.supportedbearers

Refers to the list of wireless data technologies supported by the device, including Bluetooth. If the device supports phone calls, the SMS value is also returned. See a(title='Refers to the list of wireless data technologies supported by the device, including Bluetooth. If the device supports phone calls, the SMS value is also returned.’, href='http://en.wikipedia.org/wiki/Wireless_Application_Protocol’, rel='nofollow’, target=’_blank’) Supported Bearers on Wikipedia

user.device.hardwareplatform.connectivity.supportedio

Refers to the list of input and output ports the device has, for example 3.5mm audio jack, micro-USB etc.

user.device.hardwareplatform.connectivity.supportsphonecalls

Indicates if the device can receive and make telephone calls using available bearers without any additional software such as VoIP. Devices that support voice calls do not necessarily support phone calls.

user.device.hardwareplatform.inputs.hasclickwheel

Indicates if the device has a click wheel such as in Apple iPod device.

user.device.hardwareplatform.inputs.haskeypad

Indicates if the device has a physical numeric keypad.

user.device.hardwareplatform.inputs.hasqwertypad

Indicates if the device has a physical qwerty keyboard.

user.device.hardwareplatform.inputs.hastouchscreen

Indicates if the device has a touch screen. This property will return 'False’ for a device that does not have an integrated screen.

user.device.hardwareplatform.inputs.hastrackpad

Indicates if the device has a trackpad or trackball. Examples of devices that support this property are the Nexus One and Blackberry Curve.

user.device.hardwareplatform.inputs.hasvirtualqwerty

Indicates if the device has a virtual qwerty keyboard displayed on the screen of the device.

user.device.hardwareplatform.screen.bitsperpixel

Refers to the number of bits used to describe the colour of each individual pixel; a value of 24 bits per pixel means that each pixel could be one of 16 million different colours. Also known as bit depth or colour depth.

user.device.hardwareplatform.screen.has3dscreen

Indicates if the device has a screen capable of displaying 3D images. This property will return 'False’ for a device that does not have an integrated screen.

user.device.hardwareplatform.screen.screeninchesdiagonal

Refers to the diagonal size of the device’s screen in inches. This property is not applicable for a device that does not have a screen and will return the value 'Unknown’ for desktop.

user.device.hardwareplatform.screen.screeninchesdiagonalrounded

The diagonal size of the device’s screen in inches rounded to the nearest whole number. This property will return the value 'Unknown’ for desktop or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screeninchesheight

Refers to the height of the device’s screen in inches. This property will return 'Unknown’ for desktops or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screeninchessquare

Refers to the area of the device’s screen in square inches rounded to the nearest whole number. This property will return the value 'Unknown’ for desktop or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenincheswidth

Refers to the width of the device’s screen in inches. This property will return the value 'Unknown’ for desktop or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenmmdiagonal

Refers to the diagonal size of the screen of the device in millimetres. This property will return 'Unknown’ for desktops or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenmmdiagonalrounded

Refers to the diagonal size of the device’s screen in millimetres rounded to the nearest whole number. This property will return the value 'Unknown’ for desktop or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenmmheight

Refers to the screen height of the device in millimetres. This property will return 'Unknown’ for desktops or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenmmsquare

Refers to the area of the device’s screen in square millimetres rounded to the nearest whole number. This property will return the value 'Unknown’ for desktop or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenmmwidth

Refers to the screen width of the device in millimetres. This property will return 'Unknown’ for desktops or for devices which do not have an integrated screen.

user.device.hardwareplatform.screen.screenpixelsheight

Refers to the height of the device’s screen in pixels. If the device is a desktop or laptop then an 'Unknown’ value can be returned. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel height will be the smaller value compared to the pixel width.

user.device.hardwareplatform.screen.screenpixelswidth

Refers to the width of the device’s screen in pixels. If the device is a desktop or laptop then an 'Unknown’ value can be returned. This property is not applicable for a device that does not have a screen. For devices such as tablets or TV which are predominantly used in landscape mode, the pixel width will be the larger value compared to the pixel height.

user.device.hardwareplatform.screen.screentype

Refers to the screen type of the device. This property is not applicable for a device that doesn’t have an integrated screen, e.g. a media hub. If the device manufacturer or vendor does not specify what the screen type of the device is, it is assumed the device has an LCD screen.

user.device.hardwareplatform.screen.suggestedimagebuttonheightmms

Refers to the suggested optimum height of a button in millimetres. Ensures the button is touchable on a touch screen and not too large on a non-touch screen. Assumes the actual device DPI (Dots Per Inch) is being used.

user.device.hardwareplatform.screen.suggestedimagebuttonheightpixels

Refers to the suggested optimum height of a button in millimetres. Ensures the button is touchable on a touch screen and not too large on a non-touch screen.

user.device.hardwareplatform.screen.suggestedlinksizepixels

Refers to the suggested optimum height of a hyperlink in pixels. Ensures the link is touchable on a touch screen and not too large on a non-touch screen. Assumes the actual device DPI is being used.

user.device.hardwareplatform.screen.suggestedlinksizepoints

Refers to the suggested optimum height of a hyperlink in points. Ensures the link is touchable on a touch screen and not too large on a non-touch screen.

user.device.hardwareplatform.tv.tv.contrastratio

Refers to the contrast ratio of the device. This property is applicable only for TVs.

user.device.hardwareplatform.tv.energyconsumptionperyear

Refers to the annual energy consumption of the device per year in kWh. This property is applicable only for TVs.

user.device.hardwareplatform.tv.onpowerconsumption

Refers to the power consumption of the device while switched on. This property is applicable only for TVs.

user.device.hardwareplatform.tv.refreshrate

Refers to the number of frames per second the television can display, in Hertz. This property is applicable only for TVs.

user.device.hardwareplatform.tv.supports24p

Indicates if the device supports 24p; a video format that operates at 24 frames per second. This property is applicable only for TVs.

user.device.hardwareplatform.tv.supportswidi

Indicates if the device supports Wireless Display Technology. This property is applicable only for TVs.

Hardware - market statistics

user.device.hardwareplatform.stats.popularity

Refers to the number of unique client IPs from which this device has been seen.

Software platform

user.device.softwareplatform.name.platformname

Refers to the name of the software platform (operating system) the device is using.

user.device.softwareplatform.name.platformvendor

Refers to the name of the company that developed the operating system.

user.device.softwareplatform.name.platformversion

Refers to the version or subversion of the software platform.

Browser - general

### Browser - capabilities

user.device.browserua.name.browsername

Refers to the name of the browser. Many mobile browsers, by default, come with an operating system (OS). Unless specifically named, these browsers are named after the accompanying OS and/or the layout engine.

user.device.browserua.name.browservendor

Refers to the name of the company which created the browser.

user.device.browserua.name.browserversion

Refers to the version or subversion of the browser.

user.device.browserua.general.isemailbrowser

Indicates if the application is an email browser (Outlook, Gmail, YahooMail, etc.) that is primarily used to access and manage emails (usually from mobile devices).

user.device.browserua.general.isemulatingdesktop

Indicates if the mobile device accessing a web page emulates a desktop computer. This property is not applicable for desktops, media hubs, TVs and consoles.

user.device.browserua.general.iswebapp

Indicates if a web page is accessed from an application whose main function is not browsing the World Wide Web or managing emails, e.g. the Facebook App. The application must be downloaded and installed onto the device from an app marketplace such as Apple?s App Store or the Google Play Store, or via a third party as an .apk file or similar. This property will return a 'False’ value for mobile browsers such as Chrome Mobile or email browsers (such as Hotmail).

user.device.crawler.miscellaneous.iscrawler

Indicates if the source of the web traffic operates without human interaction, primarily for the purpose of indexing the response. Such sources are typically used by search engines, and can be referred to as crawlers, bots, robots or spiders, among other terms. This property can also refer to API calls that process websites to extract the structure data.

user.device.browserua.general.touchevents

Indicates if the browser supports the method of registering and interpreting finder (or stylus) activity on touch screens or trackpads. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.ajaxrequesttype

Indicates what ajax request format should be used. May also return 'Unsupported’ or 'Unknown’.

user.device.browserua.general.animationtiming

Indicates if the browser supports 'window.requestAnimationFrame()’ method. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.blobbuilder

Indicates if the browser fully supports BlobBuilder, containing a BlobBuilder interface, a FileSaver interface, a FileWriter interface, and a FileWriterSync interface. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.browserpropertysource

Indicates the source from which browser properties have been validated. Primary browser data are retrieved from the internal test and populated manually, then they might be validated against an external source such as Caniuse or RingMark.

user.device.browserua.general.formdata

Indicates if the browser supports the 'FormData’ object. This property also refers to XMLHttpRequest and may need a vendor prefix, e.g. webkit, moz, etc. If the browser supports 'xhr2’, the 'FormData’ element will be also supported.

user.device.browserua.general.iframe

Indicates if the browser supports the 'Iframe’ element, used to embed another document within a current HTML document. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.indexeddb

Indicates if the browser supports an indexed local database. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.jquerymobilesupport

Refers to the grade of the level the device has with the jQuery Mobile Framework, as posted by jQuery.

user.device.browserua.general.layoutengine

Refers to the name of the embedded technology the browser uses to display formatted content on the screen.

user.device.browserua.general.masking

Indicates if the browser supports the CSS-mask element that allows users to alter the visibility of an item by either partially or fully hiding the item. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.postmessage

Indicates if the browser supports messages between different documents. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.prompts

Indicates if the browser supports simple dialogues (window.alert, window.confirm and window.prompt).

user.device.browserua.general.selector

Indicates if the browser supports the querySelector() method that returns the first element matching a specified CSS selector(s) in the document. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.general.track

Indicates if the browser supports a method of tracking text being played with media, e.g. subtitles and captions.

user.device.browserua.screen.fullscreen

Indicates if the browser supports requests from a video or canvas element to be displayed in full-screen mode. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.viewport.viewport

Indicates if the browser supports Viewport, to give control over view for different screen sizes and resolutions of devices accessing a website.

user.device.browserua.gps.geolocation

Indicates if the browser supports a feature to acquire the geographical location. For information on which GeoLoc API the browser supports, refer to another property called JavaScriptPreferredGeoLocApi. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.web.cookiescapable

Indicates if the browser supports http Cookies. However, the user may have disabled Cookies in their own configuration. Where data cannot be validated, it is assumed that the browser supports cookies.

user.device.browserua.web.history

Indicates if the browser stores the session history for a web page that contains the URLs visited by the browser’s user. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.web.meter

Indicates if the browser supports a meter element that represents a scalar measurement within a known range or fractional value. This property does not indicate whether the browser supports the progress bar indication. For this purpose, the progress property should be used.

user.device.browserua.web.progress

Indicates if the browser supports progress reports, such as with HTTP requests. The progress element can be used to display the progress of the task. This property doesn’t represent a scalar measurement. If the browser supports a gauge, the meter property should be used.

user.device.browserua.web.webworkers

Indicates if the browser supports background workers in JavaScript. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.web.xhr2

Indicates if the browser supports client-to-server communication with XmlHttpRequests. If the browser supports 'Xhr2’ will also support 'DataForm’ element. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.useragent

Full user-agent string

user.device.browserua.supportedmedia.supportstlsssl

Indicates if the browser supports TLS or SSL, essential for secure protocols such as HTTPS.

user.device.browserua.supportedmedia.supportswebgl

Indicates if the browser supports WebGL technology to generate hardware-accelerated 3D graphics.

user.device.browserua.supportedmedia.svg

Indicates if the browser supports SVG (scalable vector graphics), useful for 2D animations and applications where all objects within the SVG can be accessed via the DOM and can have assigned event listener elements. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.supportedmedia.video

Indicates if the browser supports the 'Video’ element for playing videos on web pages without requiring a plug-in. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.html.html5

Indicates if the browser supports the new markup in HTML 5 that also refers to 'New Semantic Elements’. This property may need a vendor prefix, e.g. webkit, moz.

user.device.browserua.html.html_media_capture

Indicates if the browser is able to use media inputs, e.g. webcam and microphone, in a script and as an input for forms, e.g. ’<input type=“file” accept=“image/*” id=“capture”>’ would prompt image- capturing software to open.

user.device.browserua.html.htmlversion

Refers to the latest version of HyperText Markup Language (HTML) supported by the browser.

user.device.browserua.css.cssbackground

Indicates if the browser supports CSS3 background properties (such as background-image, background-color, etc.) that allow styling of the border and the background of an object, and create a shadow effect. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssborderimage

Indicates if the browser supports border images, allowing decoration of the border around an object. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.csscanvas

Indicates if the browser can draw CSS images into a Canvas. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.csscolor

Indicates if the browser supports CSS3 Color, allowing author control of the foreground colour and opacity of an element. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.csscolumn

Indicates if the browser supports CSS3 columns for setting column- width and column-count. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssflexbox

Indicates if the browser supports flexbox, allowing the automatic reordering of elements on the page when accessed from devices with different screen sizes. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssfont

Indicates if the browser supports CSS3 fonts, including non-standard fonts, e.g. @font-face. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssimages

Indicates if the browser supports CSS3 images, allowing for fall-back images, gradients and other effects. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssmediaqueries

Indicates if the browser supports MediaQueries for dynamic CSS that uses the @media rule. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssminmax

Indicates if the browser supports the CSS 'min-width’ and 'max-width’ element. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssoverflow

Indicates if the browser supports overflowing of clipped blocks.

user.device.browserua.css.cssposition

Indicates if the browser supports CSS position, allowing for different box placement algorithms, e.g. static, relative, absolute, fixed and initial. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.csstext

Indicates if the browser supports all CSS3 text features including: text-overflow, word-wrap and word-break. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.csstransforms

Indicates if the browser supports 2D transformations in CSS3 including rotating, scaling, etc. This property includes support for both transform and transform-origin properties. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.csstransitions

Indicates if the browser supports CSS3 transitions elements, used for animating changes to properties. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.css.cssui

Indicates if the browser supports CSS UI stylings, including text-overflow, css3-boxsizing and pointer properties. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.javascript.canvas

Indicates if the browser supports the canvas element, useful for drawing graphics via scripting (usually JavaScript). This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.javascript.javascript

Refers to the JavaScript snippet used to determine the response times and bandwidth to monitor the performance of the website.

user.device.browserua.javascript.javascriptcanmanipulatecss

Indicates if the browser supports the JavaScript that can manipulate CSS on the browser’s web page.

user.device.browserua.javascript.javascriptcanmanipulatedom

Indicates if the browser supports the JavaScript that can manipulate the Document Object Model on the browser’s web page.

user.device.browserua.javascript.javascriptgetelementbyid

Indicates if the browser supports JavaScript that is able to access HTML elements from their ID using the getElementById method.

user.device.browserua.javascript.javascriptpreferredgeolocapi

Indicates which GeoLoc API JavaScript the browser supports. If a browser supports a feature to acquire the user?s geographical location, another property called 'GeoLocation’ will be set to True.

user.device.browserua.javascript.javascriptsupportseventlistener

Indicates if the browser allows registration of event listeners on event targets by using the addEventListener() method.

user.device.browserua.javascript.javascriptsupportsevents

Indicates if the browser supports the JavaScript events 'onload’, 'onclick’ and 'onselect’.

user.device.browserua.javascript.javascriptsupportsinnerhtml

Indicates if the browser supports the JavaScript that is able to insert HTML into a DIV tag.

user.device.browserua.javascript.javascriptversion

Indicates which JavaScript version the browser uses. The number refers to JavaScript versioning, not ECMAscript or Jscript. If the browser doesn’t support JavaScript then 'NotSupported’ value is returned.

user.device.browserua.json.json

Indicates if the browser supports the 'JSON’ object. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.file.filereader

Indicates if the browser supports file reading with events to show progress and errors. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.file.filesaver

Indicates if the browser allows Blobs to be saved to client machines with events to show progress and errors. The End-User may opt to decline these files.

user.device.browserua.file.filewriter

Indicates if the browser allows files to be saved to client machines with events to show progress and errors. The End-User may opt to decline these files.

user.device.browserua.data.dataset

Indicates if the browser has the ability to embed custom data attributes on all HTML elements using the 'data-’ prefix. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.data.dataurl

Indicates if the browser allows encoded data to be contained in a URL. This property may need a vendor prefix, e.g. webkit, moz, etc.

user.device.browserua.dom.deviceorientation

Indicates if the browser supports DOM events for device orientation, e.g. 'deviceorientation’, 'devicemotion’ and 'compassneedscalibration’. This property may need a vendor prefix, e.g. webkit, moz, etc.

Custom Data Examples

Subdomains & Mobile Domains

Usually Publisher employ various types of subdomains:

To track traffic from all subdomains you’ll need obviously to deploy DMA code across all pages. By default our system treats every subdomain as a separate site, however there are simple ways to reconfigure it to your convenience.

In the Tracking Settings you can configure default prefixes that let system know which domains should be treated separately and which data should be integrated. For example there’s a common practise to setup prefixes like “www.”, “ww2.” or “m.” to be consolidated with the main domain.

The second method to consolidate data into one main domain from other subdomains (or even completely different domains!) is to overwrite an original page domain with the one you’ll want to.

Manualy specify consolidated domain

deep({"page.domain": "yoursite.com"});

To do this just put the simple line of code on the website that should be consolidated (e.g. mobileversion.yoursite.com, mobileversionofyoursite.com etc.)

Purchase Event

Example structure of purchase event

deep.event({
 'event.type': 'purchase',
 'transaction.id': 'q1w2e3',
 'customer.id': 'r4t5y6', 
 'customer.name': 'John Doe',
 'customer.email': 'john.doe@yahoo.com'
 'product.id': ['12345'],
 'product.name': ['Monthly subscription - Premium'],
 'product.price.value': ['199'],
 'transaction.value': '199', 
 'payment.method': 'credit card'
});

If users can make purchases on your site we would recommend to track these events with all information related to the transaction in a dedicated type of event. You can see example structure for such event on the right. Use this as an indication on what might be worth tracking and how and adjust the structure of this event to your requirements.

Example purchase events:

Social Event

Example social event

deep.event({
 'event.type': 'social-media',
 'social.action': 'share',
 'social.media': 'facebook'
});

Have integrated social media plugins with your site? Start tracking how your users interact with these and collect information about channels and types of interactions (e.g. like, share).

Does your site use query parameters for various tracking purposes, (e.g. seeing people who came from an email newsletter)? Or does your site have multiple URL structures for the same page/article (e.g. domain.com/section/artcle vs m.domain.com/12345)?

By default, DMA is configured to use either the raw path or canonical links (when available). We strongly encourage implementing canonical links to ensure consistent tracking of pages and to prevent seeing multiple listings of the same page in the DMA Dashboard. If you’re not familiar with canonical links, check out Google’s Guide to Canonical Links.

Enable canonical links

deep.options.pageCanonical = true

To utilize the canonical feature, you’ll need to ensure that your site defines canonical links for each page (e.g <link rel='canonical'.../>) and that the pageCanonical option is set to true.

Custom Path Variable

Examples of setting the Path Variable

deep({"page.path": "/some/article/path"});
// or from variable
deep({"page.path": cms.path.variable});

If you are unable or prefer to not use canonical links, you may alternatively set the Path Variable. The path must start with “/” (forward slash) and we highly recommend that you use a real path used to navigate to this page. The value set for the Path Variable should be generated by your CMS or set to window.location.pathname, so that the same piece of code can be used on all pages.

Custom Page Titles

By default DMA displays page titles by using the <title> tag in your site’s header.

Here you can set the title like this

deep({"page.title": "Story Title"});
// or from variable
deep({"page.title": cms.title.variable});

You can override the title used for a page in DMA by setting the Title Variable. This can be useful when all pages have a common prefix (e.g. “Publication Name: Story Title”), or when most pages share a common site title.

You can set the title variable manually, or populate it dynamically by tying it to a variable in your CMS.

Sections & Authors

So if a page is written by Bob Johnson in the section US Politics, you would set

deep({
  section: "US Politics",
  'author.name': "Bob Johnson"
});

In DMA you can filter your content by e.g. section or author. In fact it could be any dimension that fits your site’s structure. To implement this feature, you’ll need to set up section and author variables within the DMA code.

So if a page is co-written by Megan Summers and Kevin Smith in the sections Fashion and Fashion News, you would set

deep({
  section: ["Fashion", "Fashion News"],
  "author.name": ["Megan Summers", "Kevin Smith"]
});

A page can both be in multiple sections and/or have multiple authors, therefore each variable accepts a comma separated list of values or an array of values.

Example

deep({
  section: cms.sections.variable,
  "author.name": cms.authors.variable
});

The sections variable does not need to reflect real sections on the site, but should be thought of as groupings of pages that can be filtered on. Our suggestion is to populate these fields dynamically by tying them to a variable in your CMS which globally represents your sections and authors, so they can be easily changed.

Using Page Metadata

E.g. (using jQuery helpers)

deep(function(params) {
  params.section = $("#page-info").data("section");
  params["author.name"] = $("#page-info").data("authors");
});

You can also populate these variables by using page metadata, a tag that already exists in your code, or part of your URL structure which contains these values.

In the example here we have used a function which will be called after the whole page has been already built by the browser so we can safely access any element on the page - those above and below our code.

The above code assumes that on your page there is HTML Tag with id=”page-info”

<section id="page-info" data-section="Fashion News" data-authors="Kevin Smith">

Ajax & Infinite Scroll

If your site uses infinite scroll, serves up content dynamically via AJAX, or pages change without the URL subsequently changing or the DOM refreshing, you’ll need to do some additional implementation.

You’ll need to setup logic to handle these lines of code

deep.newpage({
  'page.path':"/newpath",
  title: "New title",
  section: "New Section",
  'author.name': "New Author"
});

Anytime a visitor navigates to a new page or piece of content, you’ll need to call a custom function called page. This function is specifically designed for this kind of page change, and can be attached to click/swipe events, or to a pixel that is used to trigger content changes. Best practice is to make sure that the page function is called whenever you change to a new page of content using AJAX, so they always happen together.

For example

deep.newpage({
  'page.path':"/newpath",
  'page.title': "New title",
  section: "New Section",
  'author.name': null
});

Simply put, you’re setting the author and section (if they change) ahead of time since we take that data as holdover information when we reload the page with page(). If we are not passed the updated section and author information we’ll continue to register the original sections and authors from the previous page. If the new page has no section or author data, simply set that variable to “null”.

Next, when the page changes we’ll need to populate the path and title for the new page(s) within the page variable, so that the pings will reflect the new page the visitor is on.

Cookies

DMA uses one first-party cookies.

The _dtentr cookie is used to register if a user has visited the domain before and to calculate visitor frequency.

Disabling Cookies

To disable trakcing specify

deep.options.doNotTrack = true

Customers who are subject to the EU e-Privacy Directive, or who would prefer not to use cookies, can set the following variable to prevent DMA from using cookies

Advanced Integration Guide

After completing basic integration described at our Quick Start Guide it is now time to move on and learn about more advanced use cases of integration. Including adding tracking for custom attributes and custom events.

  1. The dimension name can contain only following characters: a-zA-Z0-9.$_-. All other characters will be changed to underline (_).
  2. The dimension name cannot exceed 255 characters. All characters above this limit will be cut off.
  3. Array of non-primitive types (e.g. array of objects) are not allowed. If you find yourself in situation where you have arrays that do not comply with this rule you should transform your event to allowed format. To do that you could use one of available data transformation, e.g. explode (see explode transformation in documentation).

Not complying with this rules may cause platform performance issues or data loss. Please, keep that in mind and in case of any questions contact us at support@deep.bi.

Tracking Custom Data

DMA allows you to add custom attributes to automatically collected events or collect your own events with their custom attributes. Examples of custom events:

Examples of custom dimensions (attributes):

Custom Attributes

Example: Add custom dimensions (attributes) to all video events

<video
  data-title="Rick Astley"
  data-author="Never Gonna Give You Up"
  width="640" height="360" autoplay controls loop
  src="http://web.advertine.com/video/Rick_Astley_Never_Gonna_Give_You_Up_medium.mp4">
</video>

If the DMA main script is loaded you can easily add custom attributes to automatically collected events. To create your own attribute follow this schema:

data-yourcustom-attribute="your custom data"

DMA will automatically replace “data-” part with an appropriate context. For example, if you place your custom attribute inside <video> tag DMA will recognize the video context and your data will look like this:

video.yourcustom.attribute="your custom data"

Custom Events

Example: Register an event when an ad has been watched

deep.event({"event.type": "ad-watched"});

Registered data:

event.type: "ad-watched"
event.timestamp: exact time of an event

Example: Register user sign up event

deep.event({
    'event.type': "signup",
    'user.id.email': "john.doe@yahoo.com"});
// or
deep.event({
    event: {type: "signup"},
    user: {id: {email: "john.doe@yahoo.com"}}});

Registered data in both examples:

event.type="signup"
event.timestamp: exact time of an event
user.id.email="john.doe@yahoo.com"

Deep Media Analytics also allows you to collect custom events with custom attributes. To trigger DMA to register an event you can use previously define global function deep (see Chapter 2). It takes as a parameter your data in JSON format.

Sensitive data

You may wish to hide sensitive data like user id or email, but still be able to calculate metrics based on them. For this you may use deep.hash(string) function which will hash data prior to sending the event.

Example: Register leaving a comment by registered user event

deep.event({
    'event.type': "user-comment-added",
    userComment: {
        from: deep.hash("some.user@mail.com"),
        inReplyTo: deep.hash("other.user@mail.com")
    }
});

Custom Data Transformations

Deep Media Analytics allows to specify custom data transformations. For the list of available data transformations see Data Transformation section.

Data Validation

Example definition of data validation

deep.options.validate = {defined: ["dimension.nameA", "dimension.nameB"], timeout: 10}

Validation method of our script allows you to validate completeness of your data before sending it do Deep platform.

Following the example, data would be send if:

  1. Properties dimension.nameA and dimension.nameB are set.
  2. After 10 seconds, if the data is still not set.

This method has no affect on values registered by the script. For example, sending the data with 5 second delay would not affect collected time of user’s attention time or time spent.

Integrations

Facebook Instant Articles

Facebook’s Instant Articles is a tool for news publishers that optimizes the article’s HTML document and enables publishers to serve the content to users much faster (even 10 times faster than traditional web content).

This section covers how to implement Deep.BI tracking with FB IA.

Implementation

Provide an URL to source of analytics code

<figure class="op-tracker">
    <iframe src="https://www.myserver.com/trackingcode"></iframe>
</figure>

Embed full source of analytics code

<figure class="op-tracker">
    <iframe>
        <!-- Include full analytics code here -->
    </iframe>
</figure>

Example embed of analytics code

<figure class="op-tracker">
    <iframe>
        <script src="https://api.deep.bi/scripts/v1/stub.min.js"></script>
        <script>
        var deep = DeepTrack.track("YOUR_STREAM_KEY","YOUR_WRITE_KEY");
        deep({
        "content.layout": "instant-article",
        "content.section": "Section Name",
        "content.author.name": "John Doe",
        "content.title": "Lorem ipsum",
        "content.type": "article",
        "content.tags": ["tag1","tag2"]
        });
        </script>
    </iframe>
</figure>

To be able to integrate FB IA you must be a registered user of Deep.BI platform with access to tracking script and your account credentials. These are mandatory to complete the integration of the Facebook’s Instant Articles.

Assuming above condition are met and your using FB IA please, follow the instruction below.

  1. Include your analytics code into an iframe within HTML5 <figure> tags.
  2. Apply op-tracker class to the <figure> element containing the code (see examples on the right).
  3. Include prepared code into the <body> section of your article. (Note: tracking within the header is not supported in the FB IA.)

Important Notes

Testing

There are two way you can test your integration of Facebook’s Instant Articles. You can open the article on the Pages Manager or use Facebook’s endpoint dedicated for faster testing, which makes possible to run a test in a browser and debug.

www.ia-tracker.fbsbx.com/instant_article_test?url=<share-url>

If you have followed above steps and you are still having troubles with integrating Facebook’s Instant Article, drop us an email at support@deep.bi. Please, describe what you did and what the problem is in your message.

Data Transformations

Deep Media Analytics script and Deep Ingestion API support custom server-side data transformation. In this section you will find how you can transform your data to adjust it to your specific needs.

More advanced applications of data transformation include:

To initiate data transformation you have to call deep transform function. Assuming you have defined previously global variable deep, calling transformation function would look like this: deep.transform();

PathSpecifier

PathSpecifier may be referred as:

"path.to.field"

or

["path", "to", "field"]

In some definitions of the transformation methods below you may see PathSpecifier. It simply points at a specific field of the event and it can be referred in two ways:

dateSplit

dateSplit definition

({
  "dateSplit": {
    "fromField": PathSpecifier,
    "toField": PathSpecifier,          // "path.to.destination" or ["path", "to", "destination"],
    "mode": "merge"                    // or "overwrite" by default
    "utcoffset": PathSpecifier         // none by default
    "unit": "seconds",                 // only when fromField is a number, default: "milliseconds"
    "epoch": "1970-01-01T00:00:00.000Z" // only when fromField is a number, default: 0
    "parts": ["year","month","weekday"] // default: "datetime weekday weekdayno utcoffset"
    "rename": { // optional mapping of date parts to field names
      "year":       "year",
      "month":      "month",
      "monthno":    "monthno",
      "day":        "day",
      "hour":       "hour",
      "minute":     "minute",
      "second":     "second",
      "fraction":   "fraction",
      "millisecond":"millisecond",
      "utcoffset":  "utcoffset",
      "weekday":    "weekday",
      "weekdayno":  "weekdayno",
      "isoweekday": "isoweekday",
      "week":       "week",
      "isoweek":    "isoweek"
    }
  }
})

Example of dateSplit usage

    deep({"published.date": "2016-03-23T23:00:01.006+02:00"}});
    deep.transform({dateSplit: {
      fromField: "published.date",
      toField: "published",
      mode: "merge"}
    });

As a result you’ll see in your analytics this data:

{
  "publication": {
    "date":"2016-03-23T23:00:01.006+02:00",
    "year": 2016,
    "month": "Mar",
    "monthno": 3,
    "day": 23,
    "hour": 23,
    "minute": 0,
    "second": 1,
    "weekday": "Wed",
    "weekdayno": 3,
    "utcoffset": 120
  }
}

A dateSplit transformation allows end user to parse collected date information (e.g. article published date) into separate dimensions like year, month, day, hour and more.

Parameter Presence Description
fromField required Source dimension
toField required Destination dimension
mode optional Values:
- overwrite (default)
- merge (keeps the original date)
utcoffset optional None by default. Allows to set time utc offset after the time has been parsed from path. A constant utc offset may be specified.
unit required* Required only when fromField is a number. Default: milliseconds
Values:
- milliseconds, msec, ms for milliseconds
- seconds, sec, s for seconds

epoch required* Required only when fromField is a number. Default: 0.
Epoch must be an ISO time string or a number of time units (milliseconds or seconds) since 1970-01-01 00:00:00 UTC.
parts optional Array of date parts to be parsed from a source dimension. Default:
["datetime weekday weekdayno utcoffset"].

Possible values:
["year","month","monthno","day","hour","minute","second","fraction","millisecond","utcoffset","weekday","weekdayno","isoweekday","week","isoweek"]

There are “shortcut” values possible to specify:
"all" - all fields are extracted
"date" - same as ["year","month","monthno","day"]
"time" - same as ["hour","minute","second"]
"datetime" - same as ["year","month","monthno","day","hour","minute","second"]
rename optional Custom mapping of date parts to field names.

explode

explode definition

({
  "explode": { 
    "fromField": PathSpecifier,   // optional if missing or empty the root object will be exploded
    "rename": "singleName",       // optional
    "keyName": "key",             // optional
    "lengthName": "length"        // optional
  }
})

With explode transformation you can produce two or more events from one, depending on the number of different values under key provided as an argument.

Parameter Presence Description
fromField optional Source dimension. If not specified root object will be exploded.
rename optional New dimension name.
keyName optional Name for the index dimension.
lengthName optional Name for the index count.


Input event:

{
  "user":{
    "email":"aaaaaaaa@gmail.com",
    "imei":"111111111"
  },
  "hits":[ 
  {
    "ts":1438326410895,
    "phoneInfo":{
      "ip":"192.168.0.24",
      "nt": "offline",
      "awaketime":21227484
    }
  },
  {
    "ts":1438326400624,
    "phoneInfo":{
      "ip":"192.168.0.24",
      "pl":"Android",
      "awaketime":21217173
    }
  }
  ],
  "deviceTs":1438326415401
}

Lets follow this with an example. We have an input event with hits key that happens to have a value with array of non primitive type, hence it does not comply with extended JSON requirements. You can use explode method to transform this event into three separate events.

Definition of transformation with explode method which takes as an argument hits field

deep.transform({  "explode": {
    "fromField": ["hits"],
    "rename": "hit"
  }
});


As a result of above transformation we get two events with new renamed key from hits to hit.

[
  {
    "user": {
      "email": "aaaaaaaa@gmail.com",
      "imei": "111111111"
    },
    "hit": {
      "ts": 1438326410895,
      "phoneInfo": {
        "ip": "192.168.0.24",
        "nt": "offline",
        "awaketime": 21227484
      }
    },
    "deviceTs": 1438326415401
  },
  {
    "user": {
      "email": "aaaaaaaa@gmail.com",
      "imei": "111111111"
    },
    "hit": {
      "ts": 1438326400624,
      "phoneInfo": {
        "ip": "192.168.0.24",
        "pl": "Android",
        "awaketime": 21217173
      }
    },
    "deviceTs": 1438326415401
  }
]

explodeToEntries

explodeToEntries definition

({
  "explodeToEntries": { 
    "fromField": PathSpecifier,   // optional if missing or empty the root object will be exploded
    "rename": "singleName",       // optional
    "keyName": "myKey",           // optional, "key" by default
    "valueName": "myValue",       // optional, "value" by default
    "lengthName": "length"        // optional
  }
})

Using explodeToEntries transformation is very similar to explode method. The only difference with this transformation is that you explode name of the key and its values to new fields.

Parameter Presence Description
fromField optional Source dimension. If not specified root object will be exploded.
rename optional New dimension name.
keyName optional Name for the index dimension. Default: key
valueName optional Name for the value of the dimension. Default: value
lengthName optional Name for the index count.

Lets use following event for an example of explodeToEntries transformation

{
  "foo": "bar",
  "other": {"different": "things"},
  "info": {
    "hits": {
      "x123": {"amount": 4},
      "ala ma kota": {"kot": "mruczek"},
      "BigHit": 100000
    }
  }
}

Definition of transformation with explodeToEntries method which takes as an argument hits field

// Notice that `keyName` and `valueName` were not specified
// default values will be used instead (respectively `key` and `value`).
deep.transform({"explodeToEntries": {
  "fromField": ["info", "hits"],
  "rename": "hit"
}});

Result of this transformation are three separate events with hit field that has two attributes fields key and value that contains source key and value.

{
  "foo": "bar",
  "other": {"different": "things"},
  "info": {
    "hit": {
      "key": "x123",
      "value": {"amount": 4}
    }
  }
}
{
  "foo": "bar",
  "other": {"different": "things"},
  "info": {
    "hit": {
      "key": "ala ma kota",
      "value": {"kot": "mruczek"}
    }
  }
}
{
  "foo": "bar",
  "other": {"different": "things"},
  "info": {
    "hit": {
      "key": "BigHit",
      "value": 100000
    }
  }
}

move

move definition

({
  "move": {
    "fromField": PathSpecifier,
    "toField": "path.to.destination",  // or ["path", "to", "destination"],
                                       // optional (if empty or not set moves to root of object)
    "mode": "merge"                    // or "overwrite" by default
  }
})

Example input event:

{
  "foo": {
    "bar": {
      "baz": 1
    }
  },
  "abc": "xyz"
}

Definition of move transformation for the event:

deep.transform({"move": {
  "fromField": ["foo", "bar"],
  "toField": ""
}});

As a result of transformation content of bar field was moved:

{
  "foo": {},
  "baz": 1,
  "abc": "xyz"
}

Move a field value to different field (path).

Parameter Presence Description
fromField required Source dimension.
toField optional Target dimension. If not specified moves the value to root of object.
mode optional Transformation type.
Values:
- overwrite (default)
- merge

delete

‘delete’ definition

({
  "delete": {
    "field": PathSpecifier
  }
})

Lets try to delete foo.bar field from following event as an example:

Input event:

{
  "foo": {
    "bar": {
      "baz": 1
    }
  },
  "abc": "xyz"
}

Definiton of transformation with delete that takes as argument foo.bar field:

deep.transform({"delete": {
  "field": ["foo", "bar"]
}});

Result event:

{
  "foo": {},
  "abc": "xyz"
}

Delete a specified field from an event.

Parameter Presence Description
field required Destination dimension.

set

set definition

({
  "set": {
    "field": PathSpecifier, // path to field
    "value": "some value"
  }
})

Example, set a new field for the following event:

{
  "user":{
    "androidID":"bec078d91ee610c5"
  },
  "hit": {
    "ts":1438326410895,
    "phoneInfo":{
      "dc":"CF"
    }
  }
}

Definition of the set transformation that adds (or overwrites if exists) event.type field to the event with phone-info as its value

deep.transform({"set": {
        "field": "event.type",
        "value": "phone-info"
}});

Transformed event with new a field:

{
  "user": {
    "androidID": "bec078d91ee610c5"
  },
  "hit": {
    "ts": 1438326410895,
    "phoneInfo": {
      "dc": "CF"
    }
  },
  "event.type": "phone-info"
}

Set new value for a data attribute. With set transformation you can set a new value (overwrite) for an existing data attribute or set a new attribute with specified value.

Parameter Presence Description
field required Destination dimension.
value required New value for the dimension.

extractEntries

extractEntries definition

({
  "extract": {
    "fromField": PathSpecifier,
    "extractKey": "key",        // default "key"
    "extractValue": "value",    // optional
    "prefixKey": "prefix",      // optional
    "suffixKey": "suffix"      // optional
  }
})

With extractEntries transformation you can extract values of the key:value pairs from an event.

Parameter Presence Description
fromField required Source dimension.
extractKey optional The name of the attribute with key name. Default: key
extractValue optional The name of the attribute with value of the key.
prefixKey optional Prefix for the extracted value.
suffixKey optional Sufix for the extracted value.

Example input event with separate key and value fields

  { 
    "foo": {
      "bar": [
        {"key": "aaa", "value": 1},
        {"key": "bbb", "value": 2},
        {"key": "ccc", "value": 3}
      ]
    }
  }

Definition of transformation with extractEntries method:

deep.transform({"extractEntries": {
  "fromField": ["foo", "bar"],
  "extractKey": "key",
  "extractValue": "value"
}});

Result event of specified transformation:

{
  "foo": {
    "bar": {
      "aaa": 1,
      "bbb": 2,
      "ccc": 3
    }
  }
}

extractEntriesWithIndex

extractEntriesWithIndex definition

({
  "extractEntriesWithIndex": {
    "fromField": PathSpecifier,
    "indexToKey": "append",     // optional or "prepend", "append" by default
    "extractValue": "value",    // optional
    "extractKey": "key",        // optional
    "prefixKey": "prefix",      // optional
    "suffixKey": "suffix",      // optional
    "joinIndexWith": ""         // optional, "." by default
  }
})

Transformation method for extracting values from an event and indexing the extracted values.

Parameter Presence Description
fromField required Source dimension.
extractKey optional The name of the attribute with key name. Default: key
extractValue optional The name of the attribute with value of the key.
prefixKey optional Prefix for the extracted value.
suffixKey optional Suffix for the extracted value.
indexToKey optional Placing of the index.
Values:
- append (default)
- prepend
joinIndexWith optional Index separator. Default: "."

Example input event from which id value is extracted from foo.bar field:

  { 
    "foo": {
      "bar": [
        {"id": 7},
        {"id": 42}
      ]
    }
  }

Definition of extractEntriesWithIndex transformation where value of id is extracted from a foo.bar field

deep.transform({"extractEntriesWithIndex": {
  "fromField": ["foo", "bar"],
  "extractValue": "id",
  "prefixKey": "id."
}});

As a result of transformation value of id was extracted to a new indexed field with a specified prefix:

{
  "foo": {
    "bar": {
      "id.0": 7,
      "id.1": 42
    }
  }
}

compact

compact definition

({
  "compact": {
    "field": PathSpecifier,    // optional (if omitted or empty compacts whole input)
    "keepEmptyObjects": true   // optional false by default
  }
})

Removes input entries with empty objects, arrays and null values. If a field is empty, the whole input is compacted. If input becomes empty, it will be left empty.

Parameter Presence Description
field optional Target field. If empty the whole input is compacted.
keepEmptyObjects optional Keeps empty objects if set to True. Default: false

Example event that contains a few null/empty fields:

{
  "event": "abc",
  "some": "property",
  "level0a": {
    "level1": {
      "level2a": {
        "date": "2016-03-23T23:00:00.006Z"
      },
      "level2b": [],
      "level2c": null
    }
  },
  "level0b": []
}

Definition of transformation with compact method with a specified level10a field for compacting:

deep.transform({"compact": {
  "field": ["level0a"]
}});

As a result of transformation entries level12b and level12c were dropped from the event:

{
  "event": "abc",
  "some": "property",
  "level0a": {
    "level1": {
      "level2a": {
        "date": "2016-03-23T23:00:00.006Z"
      }
    }
  },
  "level0b": []
}

flatten

flatten definition

({
  "flatten": {
    "field": PathSpecifier,    // optional (if omitted or empty flattens everything)
    "separator": "_",          // optional key space separator, default is "."
    "arrayDelimiter": ";"      // optional array flat join delimiter, default is ","
  }
})

Reduces the levels of nested objects within an event by creating dimensions based on them.

Parameter Presence Description
field optional Target field. If empty flattens
separator optional Space separator. Default: "."
arrayDelimiter optional Flat join delimiter ",". Default: false

Example event, notice the nested content of level10 field:

{
  "event": "abc",
  "some": "property",
  "level0": {
    "level1": {
      "level2a": {
        "date": "2016-03-23T23:00:00.006Z"
      },
      "level2b": ["a","b","c"]
    }
  }
}

Definition of flatten transformation for level10:

deep.transform({"flatten": {
  "field": ["level0"],
  "separator": "-",
  "arrayDelimiter":"_"
}});

Transformed event:

{
  "event": "abc",
  "some": "property",
  "level0": {
    "level1-level2a-date": "2016-03-23T23:00:00.006Z",
    "level1-level2b": "a_b_c"
  }
}

Flow Control

Flow Control methods allows to perform conditional data transformations on collected data.

Methods

if construct

{
  "if": {
    "condition": Condition,
    "then": Expression or ExpressionList,
    "else": Expression or ExpressionList        // optional
  }
}

case construct

{
  "case": [
    {
      "condition": Condition,
      "then": Expression or ExpressionList
    },
    {
      "condition": Condition,
      "then": Expression or ExpressionList
    },
      ...
    { "else": Expression or ExpressionList }
  }
}

switch construct

{
  "switch": {
    field: PathSpecifier,
    cases: [
      {
        "when": "ABC", "then": Expression or ExpressionList
      },
      {
        "when": "XYZ", "then": Expression or ExpressionList
      },
      {
        "when": ["Alpha", "Beta"],
        "then": Expression or ExpressionList
      },
      ...
      { "else": Expression or ExpressionList },
    ]
  }
}

Flow Control supports conditional data operations with use of if, case and switch statements. See definitions of these on the right.

Condition

For some of the conditional statements you have to specify condition. See on the right how this should look like.

condition construct

{
  FieldCondition: {
    "field": PathSpecifier,
    // additional arguments
  }
}

Example if statement with conditional use of set transformation method

{
  "if": [
    {
      "condition": {            // condition definition
        "isPlainObject": {      // `isPlainObject` condition specification
          "field": "phoneInfo"  
        }
      },
      "then": [                 // conditional operation
        {
          "set": {              // `set` transformation specification   
            "field": [
              "event.type"
            ],
            "value": "phoneInfo"
          }
        }
      ]
    }
  ]
}

FieldCondition

List of the FieldCondition values available:

LogicalModifier:

It is possible to specify more than one condition for the conditional statements using following logical modifiers:

CompareFieldCondition

is comparison

{
  "is": {
    "field": PathSpecifier,
    "compare": "eq"          // optional, by default "eq" or "="
                             // also "<" or "lt", ">" or "gt", "<=" or "lte", ">=" or "gte"
                             // also "<>" or "!=" or "neq"
                             // also "in"
    "value": Primitive or array of Primitives
  }
}

hasLength comparison

{
  "hasLength": {
    "field": PathSpecifier,
    "compare": "eq"          // optional, by default "eq" or "="
                             // also "<" or "lt", ">" or "gt", "<=" or "lte", ">=" or "gte"
                             // also "<>" or "!=" or "neq"
                             // also "in"
    "value": Primitive or array of Primitives
  }
}

For conditional data transformations you can compare value of the specific field or fields of an event using following statements:

Example: if

Example input data with two different evenType value. Lets change the value for one of this event with if statement

[
  {
    "eventType": "typeA",
    "value": 10
  },
  {
    "eventType": "typeB",
    "value": 20
  }
]

To change value of eventType you can use if with set transformation as following:

deep.transform({
    "if": {
      "condition": {
        "is": {
          "field": "eventType",
          "compare": "eq",
          "value": "typeA"
        }
      }
    },
    "then": {
      "set": {
        "field": "eventType",
        "value": "typeC"
      }
    }
});

As a result of transformation value typeA was set to typeC for one of the event that met conditions of specified transformation:

[
  {
    "value": 10,
    "eventType": "typeC"
  },
  {
    "eventType": "typeB",
    "value": 20
  }
]

Example: case

Example input data of two different events. Lets change the value for one of this event with case statement

[
  {
    "eventType": "typeA",
    "value": 10
  },
  {
    "eventType": "typeB",
    "value": 20
  }
]

To change value field for one of the events you can use case to compare the value of evenType and transform it with set method as following:

deep.transform({
    "case": [
      {
        "condition": {
          "is": {
            "field": "eventType",
            "compare": "eq",
            "value": "typeA"
          }
        },
        "then": {
          "set": {
            "field": "value",
            "value": "30"
          }
        }
      }
    ]
  }
);

As a result of transformation value of the field value was set to 30 for one of the event that met conditions of specified transformation:

[
  {
    "value": 30,
    "eventType": "typeA"
  },
  {
    "eventType": "typeB",
    "value": 20
  }
]

Example: switch

Example input data of two different events. Lets change the value for both of these events with switch statement

[
  {
    "eventType": "typeA",
    "value": 10
  },
  {
    "eventType": "typeB",
    "value": 20
  }
]

To change value field for the events you can use switch to compare the value of evenType and transform it with set method as following:

deep.transform({
    "switch": {
      "field": "eventType",     
      "cases": [
        {
          "when": "typeA",
          "then": {
            "set": {
              "field": "value",
              "value": "20"
            }
          }
        },
        {
          "when": "typeB",
          "then": {
            "set": {
              "field": "value",
              "value": "40"
            }
          }
        }
      ]
    }
  }
);

As a result of transformation value of the field value was changed accordingly to specified transformations:

[
  {
    "eventType": "typeA",
    "value": 20
  },
  {
    "eventType": "typeB",
    "value": 40
  }
]

Ingestion API

Introduction

Ingestion API lets you ingest data to deep.bi analytics engine. In this simple way you can measure your KPIs by tracking any event that people or machines generate, for example:

deep.bi Ingestion API is a HTTP REST API and it accepts data in JSON format.

Authentication

To send your data you’ll need two keys: STREAM_ID' and 'WRITE_API_KEY

STREAM_ID determines where your data will be stored. You can have any number of streams you want, for example for different stores, projects or your clients (if you provide analytics to your customers).

WRITE_API_KEY is your authorization key related to your accunt, that allows you to send data.

To get these keys please sign up for a deep.bi account at deep.bi website.

Send Event

Example JSON with buyer and purchase item data

{
    "event_type": "purchase",
    "user_id": "12345",
    "user_email": "john.doe@awesomemail.com",
    "item": "67890",
    "price": 175.00,
    "currency": "USD"
}

Sending event

curl "https://api.deep.bi/v1/streams/STREAM_ID/events/data?accessKey=WRITE_API_KEY" \
  -H "Content-Type: application/json" -d @event1.json

Let’s start with the simple case of tracking a transaction in an online store.

JSON objects are represented by keys and values. In deep.bi keys will become dimensions or metrics, depending on how do you would like your data to be interpreted. The cool thing is that you can don’t have to make the decision while ingesting data. Just send it like it is, and decide later, while querying your data for analysis.

Now we will send this event via API using a POST request. In this example we are using cURL, a command line tool. You can use any programming language you want.

Send Event with Time

Example JSON

{
  "event_type": "purchase",
  "event_time": "2015-10-12T14:42:15.123Z",
  "user_id": "12345",
  "user_email": "john.doe@awesomemail.com",
  "item": {
    "id": "67890",
    "url": "http://www.myshop.com/item/1234565",
    "name": "Nike Air Zoom Structure 19 Flash iD",
    "categories": ["clothing", "shoes", "athlete shoes"],
    "brand": "Nike",
    "color": "graphite",
    "size": 9
  },
  "price": 175.00,
  "currency": "USD"
}

Sending event with getEventTime

curl "https://api.deep.bi/v1/streams/STREAM_ID/events/data?getEventTime=purchaseTime" \
  -H "Authorization: Bearer WRITE_API_KEY" \
  -H "Content-Type: application/json" -d @event2.json

Values of event dimensions can be a string, a number or an array of strings or numbers. You can also nest objects to group dimensions under a single key.

This time we’d like to provide more data about the item, like its name, page url, item’s categories and parameters.

In the previous event we did not provide transaction timestamp, so the API has assigned the time when our server received your data. Now we want to send the time when the user actually purchased item. To do it just add a dimension containing that time and tell our API where we should look for it using the getEventTime parameter.

Send Event with Transformation

Lets use following event as an example and send it with cURL using data transformation:

[
  {
    "eventType": "typeA",
    "value1": 10,
    "value2": [1, 2, 3]
  },
  {
    "eventType": "typeB",
    "value1": 18,
    "value2": [4, 5, 6]
  },
  {
    "eventType": "typeC",
    "value1": 20,
    "value2": {
      "a": 1,
      "b": 2,
      "c": 3
    }
  }
]

Input data with specified transformation

Notice that transformation is conditional and is using logical AND modifier, hence both condition must be met so transformation would take place

{
  "transformation": {
    "case": [
      {
        "condition": {
          "and": [
            {
              "isArray": {                  
                "field": ["value2"]
              }
            },
            {
              "is": {
                "field": ["value1"],
                "compare": "lt",
                "value": 11
              }
            }
          ]
        },
        "then": {
          "move": {
            "fromField": [
              "eventType"
            ],
            "toField": [
              "newEventType"
            ],
            "mode": "merge"
          }
        }
      }
    ]
  },
  "data": [
    {
      "eventType": "typeA",
      "value1": 10,
      "value2": [1, 2, 3]
    },
    {
      "eventType": "typeB",
      "value1": 18,
      "value2": [4, 5, 6]
    },
    {
      "eventType": "typeC",
      "value1": 20,
      "value2": {
        "a": 1,
        "b": 2,
        "c": 3
      }
    }
  ]
}

Sending the data with curl request

curl "https://api.deep.bi/v1/streams/STREAM_ID/events/data?accessKey=WRITE_API_KEY" 
-H "Content-Type: application/json" --data \
'{"transformation":{"case":[{"condition":{"and":[{"isArray":{"field":["value2"]}},{"is":{"field":["value1"],"compare":"lt","value":11}}]},"then":{"move":{"fromField":["eventType"],"toField":["newEventType"],"mode":"merge"}}}]},"data":[{"eventType":"typeA","value1":10,"value2":[1,2,3]},{"eventType":"typeB","value1":18,"value2":[4,5,6]},{"eventType":"typeC","value1":20,"value2":{"a":1,"b":2,"c":3}}]}'

# or by sending the data in a json file

curl "https://api.deep.bi/v1/streams/STREAM_ID/events/data?accessKey=WRITE_API_KEY" \
  -H "Content-Type: application/json" -d @event1.json

Output event

Notice only typeA event was changed, other events have not met the condition of the transformation

[
  {
    "value1": 10,
    "value2": [
      1,
      2,
      3
    ],
    "newEventType": "typeA"
  },
  {
    "eventType": "typeB",
    "value1": 18,
    "value2": [
      4,
      5,
      6
    ]
  },
  {
    "eventType": "typeC",
    "value1": 20,
    "value2": {
      "a": 1,
      "b": 2,
      "c": 3
    }
  }
]

Data Transformation can be used with Ingestion API and they works on a similar basis as with the javascript snippet. That applies to Flow Control functions as well, since they are part of data transformations.

For more information about data transformations see following sections:

Analytics API

Get a list of dimensions

curl "https://api.deep.bi/v1/analytics/stream/<STREAM_ID>/dimensions?accessKey=<READ_API_KEY>"

Query data using query parameter authorization:

curl "https://api.deep.bi/v1/analytics/query?accessKey=READ_API_KEY" \
  -H "Content-Type: application/json" -d @query1.json

Query data using query header authorization:

curl "https://api.deep.bi/v1/analytics/stream/STREAM_ID/query" \
  -H "Authorization: Bearer READ_API_KEY" \
  -H "Content-Type: application/json" -d @query1.json

Introduction

Analytics API allows you to query your data using HTTP REST API.

Authorization

To read your data you’ll need two keys: STREAM_ID and READ_API_KEY

STREAM_ID determines which data your querying. This is the same key you are already using to send data to Deep platform.

READ_API_KEY is your authorization key related to your account, that allows you to query the data.

If you would like to get your READ_API_KEY please, contact us at support@deep.bi.

You can authorize your request by using either:

Release Notes

In this section you can find information about new and past releases of Deep.BI APIs.

November 2016

Enrichment API update.

Since November users get 200+ new data dimensions through 3rd party data enrichers available on Deep.BI platform in four categories:

To learn more please refer to: docs.deep.bi/#data-attributes

September 2016

Deep Media Analytics script update: | | | | ——— |:————| | version | 1.2.16 | | date | 2016-09-30 |

Tracking script changes:

May 2016

Deep Media Analytics script update: | | | | ——— |:————| | version | 1.2.7 | | date | 2016-05-27 |

Media Events

Deep Media Analytics script supports automatic collection of media events for HTML5 objects (audio, video). To see the list of tracked events and their attributes read more about media events here: media events documentation.

Performance Events

Deep Media Analytics script enables you to track load time of page resources. You can either track all page resources or only specified types of resources. To read more about performance events see: performance events documentation.

Error Events

Deep Media Analytics script allows you to track page errors for your service, that includes javascript or AJAX http errors. To read more about error events see: error events documentation.

April 2016

Deep Media Analytics script update: | | | | ——— |:————| | version | 1.2.1 | | date | 2016-04-18 |

We are pleased to introduce you a new version of Deep Media Analytics tracking script. New snippet changes how the data is collected and is also a step towards long term support of key features we plan to introduce to clients in the future.

DMA snippet changes:

New event structure will affect partially how you query your data through Deep Explorer. Changes within dimensions between new and a legacy script are listed in tables below.

Event dimensions

New script Legacy script
event.typeeventype
event.pingseqpingseq
event.timestampn/a
event.localtime.yearn/a
event.localtime.monthn/a
event.localtime.monthnon/a
event.localtime.hourn/a
event.localtime.minuten/a
event.localtime.weekdayn/a
event.localtime.weekdaynon/a
event.localtime.utcoffsetn/a

Page dimensions

New script Legacy script
page.domaindomain
page.titletitle
page.protocolpage.protocol
page.hostpage.host
page.hostnamepage.hostname
page.portpage.port
page.pathpage.path
page.hrefpage.href
page.searchpage.search
page.query.[parameter]n/a
page.hashpage.hash
page.loadtimepageloadTime

Referrer dimensions

New script Legacy script
referrer.protocolreferrer.protocol
referrer.hostreferrer.host
referrer.hostnamereferrer.hostname
referrer.portreferrer.port
referrer.pathreferrer.path
referrer.hrefreferrer.href
referrer.searchreferrer.search
referrer.query.[parameter]n/a
referrer.hashreferrer.hash

Attention dimensions

New script Legacy script
user.attention.activeattention.active
user.attention.idleattention.idle
user.attention.totalattention.total

Device dimensions

New script Legacy script
user.device.screen.widthscreen.width
user.device.screen.heightscreen.height
user.device.screen.availwidthscreen.availWidth
user.device.screen.availheightscreen.availHeight
user.device.screen.orientationscreen.orientation
user.device.agentagent

User ID dimensions

New script Legacy script
user.id.deepcookiecookie
user.id.ipip
user.id.sessionn/a