-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbrightove-player-viewability.html
171 lines (170 loc) · 10.2 KB
/
brightove-player-viewability.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
<h1>{{ page.title }}</h1>
<article class="bcls-article">
<summary>{{ page.description }}</summary>
<section class="bcls-section">
<h2 id="Introduction">Introduction</h2>
<p>The viewability of a player is of fundamental importance to advertising integrations as well as some UI treatments like floating players. In this context, we define “viewability” as the percentage of a player visible in the browser viewport at any given moment. A player is considered “viewable” if some specific percentage of the player is in the viewport.</p>
<p>Brightcove Player 7 introduces viewability tracking DOM events and some valuable behaviors that depend on the player’s viewable state.</p>
<aside class="bcls-aside bcls-aside--information">Please note that the viewability feature is only available for Brightcove Player 7, and no migration is needed.</aside>
</section>
<section class="bcls-section">
<h2 id="Player_configuration">Player configuration</h2>
<p>The player's viewability events and behavior can be configured in your player's JSON configuration. All configurations are available under the viewability property.</p>
<table class="bcls-table">
<thead class="bcls-table__head">
<tr>
<th>Property</th>
<th>Description</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody class="bcls-table__body">
<tr>
<td><code translate="No">pause_in_background_tab</code></td>
<td>If true, the player will automatically be paused when the browser tab is in the background.</td>
<td><code translate="No">boolean</code></td>
<td><code translate="No">false</code></td>
</tr>
<tr>
<td><code translate="No">viewability_threshold</code></td>
<td>A number between <code translate="No">0</code> and <code translate="No">1</code> representing the portion of the player that must be in the viewport for it to count as "viewable".</td>
<td><code translate="No">number</code></td>
<td><code translate="No">0.6</code></td>
</tr>
<tr>
<td><code translate="No">min_duration_for_viewable_impression</code></td>
<td>Represents the number of milliseconds to wait after ad playback begins before testing for a viewable impression.<br><br>
By default, this means that the player will report whether the ad impression was viewable using a <code translate="No">viewable-ad-impression</code> event after 2 seconds of ad playback.</td>
<td><code translate="No">number</code></td>
<td><code translate="No">2000</code></td>
</tr>
<tr>
<td><code translate="No">threshold_percentage_increment</code></td>
<td>The amount of viewability change required between <code translate="No">viewable-percent-change</code> events.<br><br>
By default, the value <code translate="No">5</code> means that <code translate="No">viewable-percent-change</code> events will only fire if the viewability of the player has changed by 5% (e.g. from 45% to 50%).<br><br>
It is recommended not to go any more granular with this as it will fire a lot of events.</td>
<td><code translate="No">number</code></td>
<td><code translate="No">5</code></td>
</tr>
<tr>
<td><code translate="No">delay_autoplay_if_not_viewable</code></td>
<td>Only interacts with players that are configured for autoplay.<br><br>
If <code translate="No">true</code>, the player delays its playback attempt until the player is viewable.<br><br>
If <code translate="No">false</code>, the player will attempt playback regardless of its viewability state. This is the default behavior of an autoplay player.</td>
<td><code translate="No">boolean</code></td>
<td><code translate="No">false</code></td>
</tr>
<tr>
<td><code translate="No">delay_autoplay_on_mobile_only</code></td>
<td>If <code translate="No">true</code>, the delay autoplay feature will only be activated on mobile environments (iOS or Android).<br><br>
<strong>NOTE</strong>: In this case, tablets are considered mobile environments.</td>
<td><code translate="No">boolean</code></td>
<td><code translate="No">true</code></td>
</tr>
<tr>
<td><code translate="No">pause_when_not_viewable</code></td>
<td>If <code translate="No">true</code>, the player will pause playback if it becomes not viewable. When the player becomes viewable again, playback will resume.<br><br>
If <code translate="No">false</code>, the player will not toggle pause or play on <code translate="No">viewable-change</code>. This is the default behavior of a player.</td>
<td><code translate="No">boolean</code></td>
<td><code translate="No">false</code></td>
</tr>
<tr>
<td><code translate="No">pause_on_blur</code></td>
<td>If <code translate="No">true</code>, the player will automatically pause when a user navigates away from the browser window to focus on another app.<br><br>
<td><code translate="No">boolean</code></td>
<td><code translate="No">false</code></td>
</tr>
</tbody>
</table>
<h3>Example</h3>
<p>Here's the JSON for a player configuration which includes viewability:</p>
<pre class="line-numbers"><code class="language-json" translate="No">{
... other properties ...
"viewability": {
"viewability_threshold": 0.3,
"pause_when_not_viewable": true
}
}</code></pre>
<p>In this example, playback pauses when less than 30% of the player is visible in the browser viewport, caused by the user scrolling the player out of view. Playback resumes when the player becomes visible again.</p>
<div style="max-width: 960px;"><style>video-js.video-js.vjs-fluid:not(.vjs-audio-only-mode) {padding-top: 56.25%;}</style><video-js data-account="1752604059001" data-player="7cdNyY7cJ" data-embed="default" controls="" data-video-id="3851380732001" data-playlist-id="" data-application-id="" class="vjs-fluid"></video-js></div><script src="https://players.brightcove.net/1752604059001/7cdNyY7cJ_default/index.min.js"></script>
</section>
<section class="bcls-section">
<h2 id="Viewability_events">Viewability events</h2>
<p>Users can hook into three new events related to viewability.</p>
<ul>
<li>
<p><h3><code translate="No">viewable-change</code></h3></p>
<p>This event fires when the player transitions to or from a viewable state.</p>
<table class="bcls-table">
<thead class="bcls-table__head">
<tr>
<th>Property</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody class="bcls-table__body">
<tr>
<td><code translate="No">viewable</code></td>
<td>boolean</td>
<td>Represents whether or not the player is in a viewable state</td>
</tr>
<tr>
<td><code translate="No">viewablePercent</code></td>
<td>number</td>
<td>Represents the percentage of the player that is currently in the viewport</td>
</tr>
</tbody>
</table>
<strong>Example</strong>
<pre class="line-numbers"><code class="language-javascript" translate="No">player.on('viewable-change', (e) => {
if (e.viewable) {
player.log('the player is viewable!');
} else {
player.log('the player is not viewable!');
}
});</code></pre>
<br>
</li>
<li>
<p><h3><code translate="No">viewable-percent-change</code></h3></p>
<p>This event fires when the viewable percentage of the player changes.</p>
<aside class="bcls-aside bcls-aside--information"><p>The frequency of this event can be influenced by the <code translate="No">threshold_percentage_increment</code> configuration, but it can fire quite often. This means performing any computationally expensive operation on this event could degrade performance.</p>
The recommendation is to use it only if it's really needed. Most use-cases just want to know when the player moves to or from a viewable state and should use the <code translate="No">viewable-change</code> event.</aside>
<table class="bcls-table">
<thead class="bcls-table__head">
<tr>
<th>Property</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody class="bcls-table__body">
<tr>
<td><code translate="No">viewable</code></td>
<td>boolean</td>
<td>Represents whether or not the player is in a viewable state</td>
</tr>
<tr>
<td><code translate="No">viewablePercent</code></td>
<td>number</td>
<td>Represents the percentage of the player that is currently in the viewport</td>
</tr>
</tbody>
</table>
<strong>Example</strong>
<pre class="line-numbers"><code class="language-javascript" translate="No">player.on('viewable-percent-change', (e) => {
player.log(`the player is ${e.viewablePercent}% viewable!`);
});</code></pre>
<br>
</li>
<li>
<p><h3><code translate="No">viewable-ad-impression</code></h3></p>
<p>This event will fire when a viewable ad impression is measured. It will not fire outside the context of ad playback.</p>
<p>In other words, once an ad has started and played for the number of milliseconds represented by <code translate="No">min_duration_for_viewable_impression</code> with the player viewable, this event will fire.</p>
<p>No additional data is passed with this event.</p>
</li>
</ul>
</section>
</article>