Skip to content

Commit 6282d2b

Browse files
jethronNivSnow
jethron
and
NivSnow
authored
Roku Tracker v0.3.0 changes (#1182)
* WIP: Roku tracker v0.3.0 docs * Conditional sections in common media tracking docs * Split Roku media tracking into versioned pages * Document Roku tracker media APIs * Complete Roku tracker changes --------- Co-authored-by: Nirvashi Ramgutty <[email protected]>
1 parent 15a6c81 commit 6282d2b

File tree

8 files changed

+489
-39
lines changed

8 files changed

+489
-39
lines changed

‎docs/reusable/media/_index.md

Lines changed: 361 additions & 22 deletions
Large diffs are not rendered by default.

‎docs/sources/trackers/roku-tracker/adding-data/index.md

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -59,20 +59,39 @@ Some subject information is filled automatically by the tracker. This includes t
5959

6060
The following table lists all the properties that can be set in tracker initialization. These are all part of the [Snowplow Tracker Protocol](/docs/sources/trackers/snowplow-tracker-protocol/index.md).
6161

62-
| Property | Description |
63-
| --------------- | --------------------------------------- |
64-
| `domainUserId` | Cookie-based unique identifier for user |
65-
| `networkUserId` | Cookie-based unique identifier for user |
66-
| `appId` | Unique identifier for application |
62+
If not provided, from v0.3.0 onwards the `domainUserId` and `domainSessionId` will be generated by the tracker and stored in the app [Registry](https://developer.roku.com/en-au/docs/developer-program/getting-started/architecture/file-system.md).
63+
This can be disabled by setting the `sessionContext` option to `false`.
64+
By default, this information is attached via the `client_session` entity, similar to mobile platforms.
65+
You can also include these values in the `domain_userid`, `domain_sessionid`, and `domain_sessionidx` fields by enabling the `sessionAsCookies` setting.
66+
67+
| Property | Description |
68+
| -------------------- | ------------------------------------------ |
69+
| `userId` | Unique user identifier in your system |
70+
| `domainUserId` | Cookie-based unique identifier for user |
71+
| `domainSessionId` | Cookie-based unique identifier for session |
72+
| `networkUserId` | Cookie-based unique identifier for user |
73+
| `appId` | Unique identifier for application |
74+
| `applicationContext` | Enable an entity with the channel version |
75+
| `sessionContext` | Whether to enable or disable session state |
76+
| `sessionAsCookies` | Enable session identifiers in atomic fields|
77+
| `userAnonymous` | Use a nil ID for the `domainUserId` value |
78+
| `sessionAnonymous` | Use a nil ID for the `domainSessionId` value |
6779

6880
Example:
6981

7082
```brightscript
7183
m.global.snowplow.init = {
7284
subject: {
85+
userId: "...",
7386
domainUserId: "...",
87+
domainSessionId: "...",
7488
networkUserId: "...",
75-
appId: "..."
89+
appId: "...",
90+
applicationContext: true,
91+
sessionContext: false,
92+
sessionAsCookies: true,
93+
userAnonymous: true,
94+
sessionAnonymous: true,
7695
}
7796
}
7897
```

‎docs/sources/trackers/roku-tracker/configuration/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Properties of the network configuration:
2323
| --- | --- |
2424
| `collector` | URI for the Snowplow collector endpoint. |
2525
| `method` | HTTP method to use. `GET` and `POST` methods are supported. |
26+
| `serverAnonymous` | Enable the `SP-Anonymous` header for server anonymization. |
2627

2728
## Tracker namespaces
2829

‎docs/sources/trackers/roku-tracker/media-tracking/index.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Media tracking"
3+
date: "2021-12-23"
4+
sidebar_position: 4500
5+
---
6+
7+
```mdx-code-block
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
```
11+
12+
Media tracking enables collecting events about audio/video playback from the [Audio](https://developer.roku.com/en-gb/docs/references/scenegraph/media-playback-nodes/audio.md) and [Video](https://developer.roku.com/en-gb/docs/references/scenegraph/media-playback-nodes/video.md) nodes provided in the Roku SceneGraph SDK for media playback.
13+
Once enabled for a node, the tracker subscribes to selected events and tracks them automatically.
14+
This makes adding media tracking into your Roku channels really simple.
15+
16+
There are [multiple versions](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/index.md) of media tracking available, and the Roku tracker supports [v1](/docs/sources/trackers/roku-tracker/media-tracking/v1/index.md) and (from v0.3.0) [v2](/docs/sources/trackers/roku-tracker/media-tracking/v2/index.md).

‎docs/sources/trackers/roku-tracker/video-tracking/index.md renamed to ‎docs/sources/trackers/roku-tracker/media-tracking/v1/index.md

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,41 @@
11
---
2-
title: "Video tracking"
2+
title: "Media tracking (v1)"
33
date: "2021-12-23"
4-
sidebar_position: 4500
54
---
65

7-
Video tracking enables collecting events about video playback from the [Video node](https://developer.roku.com/en-gb/docs/references/scenegraph/media-playback-nodes/video.md) provided in the Roku SceneGraph SDK for media playback. Once enabled for a Video node, the tracker subscribes to selected events and tracks them automatically. This makes adding video tracking into your Roku channels really simple.
6+
Media tracking has [multiple versions](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/index.md) of schema available.
7+
This document is for version 1 of the schemas, it is recommended to [migrate to v2 tracking](/docs/sources/trackers/roku-tracker/media-tracking/v2/index.md#migrating-from-v1).
88

99
## Usage
1010

11-
To start video tracking for a Video node, assign a `roAssociativeArray` with the video node to the `enableVideoTracking` property:
11+
To start media tracking for an Audio/Video node, assign a `roAssociativeArray` with the node to the `enableVideoTracking` property:
1212

1313
```brightscript
1414
m.global.snowplow.enableVideoTracking = {
15-
label: "videoLabel", ' optional
1615
video: m.Video
1716
}
1817
```
1918

20-
In addition to the video node, the `enableVideoTracking` property accepts several optional attributes listed in the table below.
19+
From tracker version 0.3.0:
20+
- You can also use `enableAudioTracking` and pass the node via `audio` instead of `video`
21+
- The v2 `enableMediaTracking` call and `media` option will also work
22+
- The tracker will use v1 tracking if the `version` option is not specified or defined as `1`.
23+
- To opt into version 2 schemas (recommended), pass the `version: 2` option to your `enableMediaTracking` call.
24+
25+
In addition to the node and version selector, the `enableVideoTracking` property accepts several optional attributes listed in the tables below.
2126

2227
| Attribute | Type | Description | Required? |
2328
| --- | --- | --- | --- |
24-
| `video` | Video | Video node to be tracked | yes |
25-
| `label` | String | An identifiable custom label sent with the event | no |
29+
| `media` / `audio` / `video` | Audio / Video | Audio/Video node to be tracked | yes |
30+
| `version` | Integer | Tracking schema version to use; defaults to 1 if not provided | no |
31+
| `label` / `options.label` | String | An identifiable custom label sent with the event | no |
2632
| `options.captureEvents` | String[] | Types of events to capture | no, defaults to all events except for `position` |
2733
| `options.boundaries` | Integer[] | Percentage boundaries in playback for which events will be sent | no, defaults to `[10, 25, 50, 75]` |
28-
| `options.positionInterval` | integer | Interval in seconds in which `position` events should be reported | no, defaults to 5 |
34+
| `options.positionInterval` | Integer | Interval in seconds in which `position` events should be reported | no, defaults to 5 |
35+
| `context` / `entities` | SelfDescribingJSON[] | Array of custom entities to include with all generated media events | no |
2936

30-
To stop tracking events from the video node, set the `disableVideoTracking` property. The tracker will then stop observing and tracking events from the video node. The property should be set with an `roAssociativeArray` with exactly one attribute, `video`, like so:
37+
To stop tracking events from the node, set the `disableVideoTracking` property. The tracker will then stop observing and tracking events from the node.
38+
The property should be set with an `roAssociativeArray` with exactly one attribute, `video` (or `audio`/`media`), like so:
3139

3240
```brightscript
3341
m.global.snowplow.disableVideoTracking = {
@@ -37,6 +45,8 @@ m.global.snowplow.disableVideoTracking = {
3745

3846
## Media Player Events
3947

48+
### Media Events
49+
4050
All playback events are tracked automatically and conform to the `media_player_event` schema. The schema has two properties:
4151

4252
| Property | Description | Required? |

‎docs/sources/trackers/roku-tracker/media-tracking/v2/index.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: "Media tracking (v2)"
3+
date: "2025-03-21"
4+
---
5+
6+
```mdx-code-block
7+
import Media from "@site/docs/reusable/media/_index.md"
8+
```
9+
10+
Media tracking has [multiple versions](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/media/index.md) of schema available.
11+
This document is for version 2 of the schemas; tracker versions earlier than v0.3.0 [only support v1 tracking](/docs/sources/trackers/roku-tracker/media-tracking/v1/index.md).
12+
13+
14+
## Configuration
15+
16+
Most tracking of [Audio](https://developer.roku.com/en-au/docs/references/scenegraph/media-playback-nodes/audio.md) and [Video](https://developer.roku.com/en-au/docs/references/scenegraph/media-playback-nodes/video.md) nodes is automatic, so configuration is minimal.
17+
18+
For backwards compatibility with [v1 media tracking](/docs/sources/trackers/roku-tracker/media-tracking/v1/index.md), most options will accept either `roAssociativeArray` format in the `enableMediaTracking` call as long as `version` is specified as `2`.
19+
20+
The accepted options include:
21+
22+
| Attribute | Type | Description | Required? |
23+
| --- | --- | --- | --- |
24+
| `media` / `audio` / `video` | Audio / Video | Audio/Video node to be tracked | yes |
25+
| `version` | Integer | Tracking schema version to use; should be set to 2 | yes |
26+
| `id` | UUID | A unique ID to use for the media `session` entity to group all tracked events | no; generated by tracker if not provided |
27+
| `label` / `options.label` | String | An identifiable custom label sent with the event in the `media_player` entity | no |
28+
| `sessions` | boolean | Whether to attach the media `session` entity on tracked events | no; defaults to `true` |
29+
| `pings` | boolean | Whether to periodically generate media `ping_event`s while content is playing | no; defaults to `true` |
30+
| `pingInterval` / `options.positionInterval` | Integer | Interval in seconds in which `ping_event`s should be reported | no, defaults to `30` seconds |
31+
| `boundaries` / `options.boundaries` | Integer[] | Percentage boundaries in playback for which `percentage_progress_event`s will be sent | no, defaults to `[25, 50, 75]` |
32+
| `captureEvents` / `options.captureEvents` | String[] | Types of events to capture. If specified, the event names should not have the `_event` suffix | no, defaults to all events |
33+
| `context` / `entities` | SelfDescribingJSON[] | Array of custom entities to include with all generated events | no |
34+
35+
## Migrating from v1
36+
37+
If you are migrating from the v1 tracking, v2 has compatibility options to make the change easier.
38+
39+
For backwards compatibility with the earlier tracking API, you can use `enableVideoTracking` instead of `enableMediaTracking`, and pass the node via the `video` option instead of `media`.
40+
For symmetry, `enableAudioTracking` and `audio` will work as well; the tracking will work with any combination of these method and option names regardless of node type, as long as `version: 2` is specified.
41+
You can also specifically opt into version 1 by passing `version: 1`.
42+
43+
The additional options differ by version; but version 2 will accept the options from version 1 if it can't find the newer equivalent settings.
44+
45+
| v2 Attribute | v1 Fallback | Type | Description |
46+
| --- | --- | --- | --- |
47+
| `media` / `audio` / `video` | `media` / `audio` / `video` | Audio / Video | Audio/Video node to be tracked |
48+
| `version` | `version` | Integer | Tracking schema version to use; should be set to 2 |
49+
| `id` | N/A | UUID | A unique ID to use for the media `session` entity to group all tracked events |
50+
| `label` | `options.label` | String | An identifiable custom label sent with the event in the `media_player` entity |
51+
| `sessions` | Default enabled | boolean | Whether to attach the media `session` entity on tracked events |
52+
| `pings` | Default enabled | boolean | Whether to periodically generate media `ping_event`s while content is playing |
53+
| `pingInterval` | `options.positionInterval` | Integer | Interval in seconds in which `ping_event`s should be reported |
54+
| `boundaries` | `options.boundaries` | Integer[] | Percentage boundaries in playback for which `percentage_progress_event`s will be sent |
55+
| `captureEvents` | `options.captureEvents` | String[] | Types of events to capture. If specified, the event names should not have the `_event` suffix |
56+
| `context` / `entities` | `context` | SelfDescribingJSON[] | Array of custom entities to include with all generated events |
57+
58+
59+
## Media Player Events
60+
61+
```mdx-code-block
62+
<Media tracker="roku" />
63+
```

‎src/componentVersions.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export const versions = {
1313
phpTracker: '0.9.2',
1414
pixelTracker: '0.3.0',
1515
pythonTracker: '1.0.3',
16-
rokuTracker: '0.2.0',
16+
rokuTracker: '0.3.0',
1717
rubyTracker: '0.8.0',
1818
rustTracker: '0.2.0',
1919
scalaTracker: '2.0.0',

‎static/_redirects

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,8 @@ docs/understanding-tracking-design/managing-data-structures-with-data-structures
167167
/docs/getting-started-on-snowplow-open-source/quick-start-gcp/summary-of-what-you-have-deployed/ /docs/getting-started-on-snowplow-open-source/what-is-deployed/ 301
168168
/docs/getting-started-on-snowplow-open-source/quick-start-aws/upgrade-guide/ /docs/getting-started-on-snowplow-open-source/upgrade-guide/ 301
169169

170+
/docs/sources/trackers/roku-tracker/video-tracking/ /docs/sources/trackers/roku-tracker/media-tracking/ 301
171+
170172
# Combining JS tracker docs
171173
/docs/collecting-data/collecting-from-own-applications/javascript-trackers/browser-tracker/quick-start-guide/ /docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/quick-start-guide/ 301
172174
/docs/collecting-data/collecting-from-own-applications/javascript-trackers/browser-tracker/cookies-and-local-storage/ /docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/cookies-and-local-storage/ 301

0 commit comments

Comments
 (0)