> General information

General information

Before getting started it is good to understand how the NPOTag SDK works, what the main concepts are and how you can use them. To directly jump to an implementation guide, see the Getting started documentation pages.

Broadly speaking, the NPO Tag measures the supply (content/pages/views) and demand (visits/streams/clicks) of the platform where the tag is implemented.

Pages (web) / ContentViews (App) : how many users see a specific page / screen?
Streams : how many users watch which videos for how long?
Recommendations : what pieces of content we show on a page, at the end of a video or as a search result, do people click on?
Clicks : which buttons draw people to a page, view or other piece of functionality

Plugins

Plugins correspond to the data collectors that you want to use (in other words, where your events will be sent). When initializing the NPOTag SDK, you’ll have to specify which plugins you’re integrating. See Plugins for a guide on available plugins and configuration.

See the Plugin documentation for stored values which may need to be reported in your cookie consent system!

Trackers

Trackers are the objects that actually collect data and send it to the different plugins. There are different trackers for different needs. The tracker that you’ll probably use the most is the PageTracker, which is used to send events tied to certain pages (e.g. page view events). The trackers that are currently available are:

PageTracker: Send events tied to the user being on a certain page (also used for click measurements).
StreamTracker: Send events tied to the user watching a video (e.g. pause, resume, seek, time, etc…)
RecommendationTracker: Send events tied to offers being presented to the user, and choices that they then make.

PageTracker is the top-level tracker. It will be used to instantiate other trackers as they will share the same properties because they are also bound to a certain page. See Getting started for a guide on how to create trackers and use them to send events.

Contexts and event properties

There are three types of event properties:

Context properties: that will be bound to a tracker and will be persisted for each event sent by this tracker. These will be passed when instantiating a tracker.
Inferred properties: that do not need to be set by the implementer but which will be inferred by the sdk and sent in each event.
One time properties: that will only apply to one event. Those will be passed as parameters of the tracker event methods.

There are different Context objects that will each contain properties related to a certain context level. For instance NPOContext is the top-level context, it will be used when configuring the SDK and the properties of this context will be shared by all events. PageContext on the other hand is a page-level context, it will be used when creating a PageTracker object and will contain all the properties shared by all events sent from that particular page. Same goes for StreamContext, RecommendationContext, and so on…

Below is a more detailed description of each Context object and the different properties that it exposes:

NPOContext

Used upon initial configuration of the SDK. Immutable once created, properties will be shared by all events.

field	field type	required	PIANO name (if available)	comments
brand	string	true		brand of the platform the tag is implemented in (e.g npostart)
brand_id	int	true	`site`	integer associated with the brand (ask publieks-onderzoek)
platform	string	true	`platform`	`site` for website, `app` for iOS/Android, `tvapp` for SmartTVs (inc. AppleTV/AndroidTV), `settopbox` for settopboxes
platform_version	string	true	`platform_version`	version of the site/app, e.g. `v1.2.3` so changes in behavior can be attributed to new features/bugfixes
user_id	string	false		id associated with the currently logged in user (set by login, logout functions), prefixed with `npo_` in govolte
user_profile	string	false		id associated with the currently selected profile (set by login, logout functions), prefixed with `npo_` in govolte
user_subscription	string	false	`user_type`	subscription type othe the currently logged in user (set by login, logout functions), prefixed with `npo_` in govolte
user_pseudoid	string	false		new ID type that will be used by platforms leveraging the new NPO-ID (set by login, logout functions), `user_pseudo_id` in govolte
environment	string	false		set this to denote the environment in which the tag is applied. Allowed values are `dev`, `preprod` or `prod`.
debug	boolean	false		set this to true to see additional logging of events
disable_nmo_dam	boolean	false		set this to true to block any funcionality related to the NMO DAM. If not set, defaults to `false`

There is an exception for all user properties (user_*), those are not settable at initialisation. Implementor will need to use the login and logout methods on NPOTag to set them. See this page for an implementation guide.

PageContext

Used for instantiating a PageTracker object. Immutable once created, properties will be shared by all events sent from this page. Check PageTracker for all the functions that it exposes.

field	field type	required	PIANO name (if available)	comments
chapter_1	string	false	`page_chapter1`	the top-level context (follow tag-plan), prefixed with `chapters_` in govolte
chapter_2	string	false	`page_chapter2`	a narrower context (follow tag-plan), prefixed with `chapters_` in govolte
chapter_3	string	false	`page_chapter3`	most specific context (follow tag-plan), prefixed with `chapters_` in govolte
page	string	false	`page`	the page or view that is displayed, set as `page_name` in govolte
content_context_id	string	false	`contextID`	ID of the central content of the page. Used on pages that feature specific content, such as an episode.
experiment	string	false		The experiment name in which the A/B conditions occur
condition	string	false		A/B condition indicator
query_context	string	false	`ise_keyword`	the query that generated the result page a user is on. `rec_query` in govolte
custom_label1	string	false	`customlabel_1`	free-form string variables for backward compatibility
custom_label2	string	false	`customlabel_2`	free-form string variables for backward compatibility
custom_label3	string	false	`customlabel_3`	free-form string variables for backward compatibility
custom_label4	string	false	`customlabel_4`	free-form string variables for backward compatibility
custom_label5	string	false	`customlabel_5`	free-form string variables for backward compatibility
error_code	string	false	`error_code`	arbitrary error code when reaching an error page
broadcasters	string	false	`omroep`	a string value, where implementers fill in a `_\|_` delimited list of lowercased broadcaster names
program	string	false	`programma`	lowercased, whitespace stripped name of a program on the page, filled in by implementers
location	string	false	`location`	current page url (only available on apps - on web this is an inferred property)
referrer	string	false	`referrer`	url of the page where you came from (only available on apps - on web this is an inferred property)

StreamContext

Used for instantiating a StreamTracker object. Immutable once created, properties will be shared by all events sent for this video or live stream. Check StreamTracker for all the functions that it exposes.

field	field type	required	PIANO name (if available)	comments
stream_length	float	true	`av_content_duration`	length of stream in seconds
stream_id	string	true	`av_content_id` AND `av_content`	ID of the content being played
player_id	string	true	`av_player`	ID of the player used, `stream_player_id` in govolte
av_type	string	true	`av_content_type`	`video` or `audio`
player_version	string	true	`player_version`	version of the player SDK
sko_player_version	string	true	`av_player_version`	player version for Stichting KijkOnderzoek, not available in `govolte`

RecommendationContext

Used for instantiating a RecommendationTracker object. Immutable once created, properties will be shared by all events sent for this recommendation. Check RecommendationTracker for all the functions that it exposes.

field	field type	required	comments
panel_id	string	true	identifier of this panel. `rec_panel` in govolte
total_offers	int	true	total amount of items in this panel , `rec_destinations.number_displayed` in govolte
panel_format	string	true	the UX-format of the panel
panel_position	int	false	the position of the panel on the page, can be absent for panels such as a search-results pop-over

PIANO does not include recommendation measurements

ClickContext

field	field type	required	PIANO name	comments
click name	string	true	`click`
click_type	string	true	`event_name`	`navigation`, `action`, `exit`, `download` or another string in exceptional cases
click_chapter_1	string	false	`click_chapter1`
click_chapter_2	string	false	`click_chapter2`
click_chapter_3	string	false	`click_chapter3`

Inferred properties

field	field type	PIANO name (if available)	comments
client_timestamp	string		timestamp of the event in ISO8601 format
sdk_version	string	`sdk_version`	the semantic version string of the sdk used to generate the event

Events

As an implementor you will never manipulate events themselves. All events will be sent using tracker methods and constructed by the SDK to infer all of the various properties (custom properties set by the implementor, device-related properties, event timestamp, etc).