Data dictionaries
Application Data Dictionary
The Datazoom Application Data Dictionary defines the standard events, metadata, and fluxdata associated with a user’s journey through your application, outside of the media player. These data points are automatically made collectable by the Datazoom SDK when you initialize an Application Collector.
Key Features:
Configurable: You can toggle the collection of any data point in this dictionary on or off at any time via the Datazoom Console.
Extensible: In addition to these standard definitions, you can instrument the SDK to collect unlimited custom events and metadata to track unique application behaviors.
Context: This dictionary serves as the foundation for your data, which can be extended by the Media Player and Ad Framework dictionaries when media is present.
Events
Discrete occurrences driven by user interactions or system actions
Metadata
Attributes describing the context of an event
Custom
Device
Location
Network
Fluxdata
Metrics measuring changing parameters over time
Events
Custom Event
{custom_event_name}
Add any event to the Datazoom data stream. Requires customer to implement a Datazoom method into their app. https://help.datazoom.io/getting-started/how-to-send-custom-events-and-metadata
| Supported Collectors | 5 |
Datazoom Loaded
datazoom_loaded
Signifies that the Datazoom SDK has been loaded and activated.
| Supported Collectors | 5 |
Metadata
Network
ASN
asn
Autonomous System Number: a unique number identifying a group of IP networks that serves the content to the end-user. Client ASN as determined from a lookup of the client IP.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
ASN Org
asn_org
The organization that owns the Autonomous System Number. Often an ISP, sometimes a private company or institution.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
ISP
isp
Name of the end user's internet service provider.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
Mobile Connection
mobile_connection
Whether the user is on a mobile connection as determined by their IP address.
| Supported Collectors | 5 |
| Data type |
bool
|
| Number Type |
Not set
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
| Permitted Values |
value list
|
Device
Ad Blocker
ad_blocker
Whether an ad blocker was detected or not. Web only.
| Supported Collectors | 1 |
| Data type |
bool
|
| Number Type |
Not set
|
| Permitted Values |
value list
|
Ad Tracking Opt Out
ad_tracking_opt_out
Whether the user has opted out of advertising tracking on their device.
| Supported Collectors | 3 |
| Data type |
bool
|
| Number Type |
Not set
|
| Permitted Values |
value list
|
Advertising ID
advertising_id
Advertising ID depends on the device platform: -- Apple: IDFA (https://developer.apple.com/documentation/adsupport/asidentifiermanager/advertisingidentifier) -- Android: AAID (https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/AdvertisingIdClient) -- Roku: RIDA (https://developer.roku.com/en-gb/docs/developer-program/advertising/roku-advertising-framework.md) -- Javascript: depends on device platform
| Supported Collectors | 4 |
| Data type |
string
|
| Number Type |
Not set
|
Browser Height
browser_height
The height of the end user's browser window at the time the event occurred.
| Supported Collectors | 1 |
| Data type |
number
|
| Number Type |
Long
|
| Unit |
pixels
|
Browser Name
browser_name
Name of the web browser according to the user agent
| Supported Collectors | 1 |
| Data type |
string
|
| Number Type |
Not set
|
Browser Version
browser_version
Version of the web browser according to the user agent
| Supported Collectors | 1 |
| Data type |
string
|
| Number Type |
Not set
|
Browser Width
browser_width
The width of the end user's browser window at the time the event occurred.
| Supported Collectors | 1 |
| Data type |
number
|
| Number Type |
Long
|
| Unit |
pixels
|
Cookies Enabled
cookies_enabled
Does the user's browser have cookies enabled?
| Supported Collectors | 1 |
| Data type |
bool
|
| Number Type |
Not set
|
| Permitted Values |
value list
|
Device ID
device_id
Unique identifier of the user's device. -- Javascript: DZ generated UUID-V4 -- iOS / tvOS: IDFV (identifierForVendor) -- Android: DeviceID -- Roku: ChannelClientID
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
Javascript: persists in the browser’s localStorage and is reused in different app sessions on the same browser. When the Device Id data point is deselected in the data pipe, data is deleted from the browser's localStorage.
iOS / tvOS: IDFV is assigned to all apps by one vendor. It does not persist once all vendor apps are uninstalled.
Android: randomly hex string generated on first boot and persists for the lifetime of the device.
Roku: a combination of deviceInfo and channel (i.e., app) info and is unique for that device/app combination. Not affected by opting out.
|
Device Manufacturer
device_mfg
Manufacturer of the user's device.
| Supported Collectors | 3 |
| Data type |
string
|
| Number Type |
Not set
|
Device Name
device_name
Name of the user's device model
| Supported Collectors | 3 |
| Data type |
string
|
| Number Type |
Not set
|
Device Type
device_type
The type of the user's device
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Required |
true
|
| Permitted Values |
value list
|
Orientation
orientation
Whether the user's mobile device is in portrait or landscape mode.
| Supported Collectors | 2 |
| Data type |
string
|
| Number Type |
Not set
|
| Permitted Values |
value list
|
OS Name
os_name
The name of the operating system of the user's device.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
OS Version
os_version
The version of the operating system of the user's device.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
User
App Session ID
app_session_id
Datazoom generated UUID for the user's Datazoom session.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Required |
true
|
App Session Start Timestamp
app_session_start_ts_ms
Start time of the Datazoom app session
| Supported Collectors | 5 |
| Data type |
number
|
| Number Type |
Long
|
| Unit |
milliseconds
|
Client IP Address
client_ip
Public IP address of the end user's device
| Supported Collectors | 4 |
| Data type |
string
|
| Number Type |
Not set
|
| Permitted Values |
IP address
|
User Agent
user_agent
For web collectors, this is the browser's defined string for user agent. For application collectors, Datazoom composes a psuedo-user agent that contains a number of tokens that refer to aspects of the user device.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
Location
City
city
The city or town where the user is located
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
When aggregated with other player sessions, this can provide a definitive number of viewers within a city. This can be helpful when targeting local advertising.
|
Continent
continent
The name of the continent from which the event originated based on the user's IP address.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
Continent Code
continent_code
The continent from which the event originated based on the user's IP address.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
| Permitted Values |
2 letter code
|
Country
country
Full name of the user's country
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
For content rights that have global distribution, country is often the value most used to enforce access making it relatively easy to blacklist and/or whitelist certain countries.
|
Country Code
country_code
The country from which the browser initiated the event. For a list of country codes, see ISO 3166-1 alpha-2 .
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
| Permitted Values |
2 letter code
|
District
district
The district, subdivision of city from where the event originated as determined by the user's IP address.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
Latitude
latitude
Location information for the user
| Supported Collectors | 5 |
| Data type |
number
|
| Number Type |
Float
|
| Unit |
degrees
|
| Notes |
When used in conjunction with longitude, this can provide an exact location for the viewer.
|
Longitude
longitude
Location information for the user
| Supported Collectors | 5 |
| Data type |
number
|
| Number Type |
Float
|
| Unit |
degrees
|
| Notes |
When used in conjunction with latitude, this can provide an exact location for the viewer.
|
Postal Code
postal_code
The specific administrative division within a country where the event occurred. In the United States, zip codes correspond to postal region locator
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
When aggregated with other player sessions, this can provide a definitive number of viewers within a specific area of a city. This can be helpful when targeting local advertising.
|
Region
region
The specific administrative division within a country where the event occurred. In the United States, regions correspond to state names ; for example, Washington or New York.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
This is the full form of the regionCode (i.e., Florida instead of FL). As a result, this value is often used for display purposes, rather than programmatically. If the fullname of a country region is needed, pulling this field is more efficient than employing memory or CPU to programmatically match the regionCode to a region name.
|
Region Code
region_code
The specific administrative division within a country where the event occurred. In the United States, regions correspond to state abbreviations; for example, WA or NY but in other countries the region code may be represented by numbers or some other identifier.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
Like the countryCode, this value can be used to enforce content rights, especially when those rights are tied to only certain regions within a country. For example, a sporting event on the West Coast of the U.S. may not be available on the East Coast of the U.S., therefore all states on the East Coast (NY, FL, NH, etc.) would be blocked from content access.
|
Timezone Name
timezone_name
The name of the user's timezone where the event originated based on their IP address.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
Timezone Offset
timezone_offset
The difference in hours, relative to UTC, of the user's timezone.
| Supported Collectors | 5 |
| Data type |
number
|
| Number Type |
Float
|
| Unit |
hours
|
| Notes |
This value is ideal to utilize when enforcing content rights: any player identified within a specific country can be blocked from accessing the content. Note that proxy servers can be used by viewers to make their request appear to be originating from an approved country. Matching the countryCode received during a request to the country specified in the subscriber's profile information can help mitigate proxy use.
|
System
Configuration ID
configuration_id
Datazoom generated identifier for the collector configuration
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Notes |
Allows customers to differentiate data on the Connector from different Collectors (e.g., could be useful for separating test content from production data).
|
| Required |
true
|
| Permitted Values |
UUID
|
DZ SDK Version
dz_sdk_version
Version number of the Datazoom SDK that generated the event message.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Required |
true
|
Event ID
event_id
Unique identifier for each event message fired by a Collector or log file received by Datazoom. The string includes an incremental counter at the end to allow for sequencing the events from a user session.
| Supported Collectors | 5 |
| Data type |
string
|
| Number Type |
Not set
|
| Required |
true
|
Custom
Custom Metadata
{custom.metadata_name}
Customers can add any user or system data to the Datazoom data stream. Requires custom coding on the page or in the app by customer developer.
| Supported Collectors | 5 |
| Number Type |
Not set
|
Page
Page Title
page_title
The title property of the web page.
| Supported Collectors | 1 |
| Data type |
string
|
| Number Type |
Not set
|
Page URL
page_url
The address of the web page.
| Supported Collectors | 1 |
| Data type |
string
|
| Number Type |
Not set
|
| Permitted Values |
URL
|
Referrer URL
referrer_url
The URL of the page the user from which the user navigated before coming to the active page.
| Supported Collectors | 1 |
| Data type |
string
|
| Number Type |
Not set
|
| Permitted Values |
URL
|
Site Domain
site_domain
The domain of the site.
| Supported Collectors | 1 |
| Data type |
string
|
| Number Type |
Not set
|
Fluxdata
Engagement Duration (App Session)
engagement_duration_ms
Cumulative time of the app session. Event timestamp minus the timestamp of the app session start minus background time.
| Supported Collectors | 5 |
| Device Platforms |
Browser,Console,DTV,Mobile
|
Event Count (App Session)
event_count
Count of events in an app session.
| Supported Collectors | 5 |
| Device Platforms |
Browser,Console,DTV,Mobile
|
| Required |
true
|