Integrating Third-Party Players with IQ Using the JSON API

Use the new Ooyala IQ JSON API to communicate
your third-party player's events to Ooyala IQ. You can use this endpoint to send
JSON data to Ooyala IQ or you can use one of the out-of-the-box SDKs. For this
release, we are offering an out-of-the-box SDK for Roku.

The Ooyala IQ SDK for Roku sends JSON data to the Ooyala JSON API
endpoint and automatically follows the best practices for what events should be sent
when, and makes sure that all required fields are present. We recommend using the
Ooyala IQ SDK for Roku with your Roku integrations, as it makes the Ooyala IQ
implementation easier. For more details on the Ooyala IQ SDK for Roku, see Ooyala IQ SDK for Roku Integration.

Events

Ooyala IQ needs to receive information about player events to
properly display analytics data. The figure below shows the flow of when each player
event should be recorded.

playerLoad: Called when the player has first
loaded.

display: Called when the media is ready (title,
description, other metadata). This may or may not include the video itself.
This is equivalent to the display metric in Ooyala
IQ.

playRequested: Called when the user clicks the play
button or autoplay occurs.

videoStarted: Called when the actual non-ad video
content starts playing.

bucketWatched: Called to capture which part of the
video the viewer has watched (position dependent). The video is divided into
40 buckets. If the viewer watches the first bucket of the video (0-2.5%) and
then skips to the last bucket (97.5-100%) and watches it, you should send
two bucket watched events [0-2.5%] and [97.5%-100%].

There are 40
buckets, where each bucket is of size 25 denoting 2.5%. If the viewer
watches the same part (bucket) of the video again and again, that
viewing event should be sent each time it is watched (the player should
not de-duplicate views of the same part of the video). For example, if a
viewer watches the 2.5% - 5% bucket over and over again for 5 times, you
should send the event 5 times.

This metric is per-mille, with the
payload being from and to of the bucket. There are 40 buckets total for
a video, where each bucket is of size 25 denoting 2.5%. If you see from:
1 and to: 25, that means the viewer has watched bucket number
1.

playthroughPercent: Called to mark the completion of a
quartile (25%, 50%, 75% and 100%) of the media. This indicates that the user
has reached the % completion via seeking to the quartile or watching the
video. Once a playthrough event has been generated, rewinding the video
should not resend the playthrough event for that quartile.

timePlayed: Called to capture the amount of time the
media has played since the last timePlayed event.

percentageWatched: Called to capture the percentage of
the video that the viewer has watched (position independent). The video is
divided into 40 buckets. If the viewer watches the first bucket of the video
(0-2.5%) and then skips to the last bucket (97.5-100%) and watches it, you
should send two percentage watched events [0-2.5%] and [2.5%-5%].

If the
viewer watches the same part (bucket) of the video again and again, that
viewing event should only be sent once (it’s the player’s responsibility
to de-duplicate views of the same part of the video). If you add all the
percentage watched for a viewer while they were watching a video, it
should always be <= 100%.

This metric is per-mille,
with the payload being from and to of the bucket. There are 40 buckets
total for a video, where each bucket is of size 25 denoting 2.5%. If you
see from: 1 and to: 25, that means the viewer has watched bucket number
1.

playheadUpdate: Called when the video playhead moves.
This should be called often (every 2-3 seconds).

seek: Called when the video has been seeked.

pause: Called when the video is paused.

resume: Called when the play button is clicked while
the video is in the pause state.

replay: Called when the video has been requested to be
replayed.

Custom Event: Called to coordinate with an event that you
define.

Note: At this time custom events can be ingested, but we can only
store the information. Ooyala IQ is not able to process custom events,
and you will not be able to access this information from the Ooyala IQ
backend. However, you may wish to start sending Ooyala IQ your custom
events now so that you have the data there for when custom events are
supported by Ooyala IQ.

Additional Data

Ooyala IQ can also collect details about the following from
the player and your JSON input for analytics purposes:

User details.

Device details.

Asset details.

Geographic location details.

Note: Ooyala IQ expects latitude and longitude
values to be integers.

Player details.

Custom dimensions.

Note: At this time custom dimensions can be ingested, but
we can only store the information. Ooyala IQ is not able to process
custom dimensions, and you will not be able to access this information
from the Ooyala IQ backend. However, you may wish to start sending
Ooyala IQ your custom dimension now so that you have the data there for
when custom dimensions are supported by Ooyala IQ.

Best Practices

Only send data to Ooyala in the intervals specified in the API documentation. Each
event is marked with a priority that indicates how often it should be sent (high
indicates to send the data every second, mid indicates to send the data every 5
seconds, and low indicates to send the data every 10 seconds).

To integrate your Smart TVs and other devices with Ooyala IQ, you need to send
specific metadata and your player's event data to the Ooyala IQ JSON API
endpoint. For this release, we support an out-of-the-box SDK for Roku. For more
details on the Ooyala IQ SDK for Roku, see Ooyala IQ SDK for Roku Integration.

Other platforms can be supported as well through an Ooyala Professional Services
engagement, at a cost. Alternatively, you can create your own SDK to hit the
JSON API endpoint directly. If you create an SDK, you will need to host
it.

If you create an SDK, the SDK must report certain events and information in a
specific order to the Ooyala IQ JSON API. The general idea is that whenever
the player changes state, event data should be sent to Ooyala IQ. See the
figure in the Events section above for the order in which events must be
captured.

After you have created your adapter, hit the JSON API endpoint via HTTP or
HTTPS request to send the properly formatted JSON to Ooyala IQ.