SDK Primer

Triton Digital API Primer

Introduction

This document describes the essential information required for the successful integration of Triton Digital’s streaming services in a context where the publisher wants to integrate at the protocol/API level and NOT use the SDK. The objective is to help the publisher to integrate to the Triton Digital streaming services directly, without using the Triton Digital SDK. If you are looking for the SDK implementation, please reach out to Triton Digital to get the right set of documents.

This API Primer assumes you are familiar with certain concepts that are considered common knowledge among Web, Android, and iOS mobile app developers, such as (but not limited to):

• How to use Xcode for Apple development.
• How to use and integrate https://google.github.io/ExoPlayer/ in your Android code.
• Understanding of how build URL strings (URL encoding, Base64 encoding, passing URL parameters and GET/POST requests).
• Using Web Sockets.
• General knowledge of working with Epoch timestamps and converting them to human-readable format.
• General knowledge of parsing, VAST, and advertising code integration.

Reference Documents

This document provides high-level information and references a number of other Triton Digital user documents where you can find a greater level of detail. 

Referenced documents include:

• Triton Digital Streaming Specification
• Triton Digital On-Demand Specification
• Triton Digital Advertising Technical Specification
• Triton Digital Mobile SDK (Android)
• Triton Digital Mobile SDK (iOS)

Essential Functionality

In broad strokes, the essential functionality is to connect to the correct mount(s) on the Triton Digital Live Streaming Network with a URL that ensures compliance with some basic connection, live stream, and measurement rules. In addition, your player or app may connect to get On-demand advertising calls (typically pre-rolls). This On-demand ad functionality is optional, since most clients prefers that the ads are inserted by the streaming servers, and not managed by the player/apps.

Live Streaming:

• Connect to the stream and play the stream audio.
• Insure compliance (prevent double play, prevent "pause," backoff for connectivity).
• Read the stream’s metadata and react to events such as breaks and advertisement insertions.
• Display and report any events relative to VAST/DAAST.
• Establish connection methods and build the parameter list (for parameters that the player passes to the Triton Digital Streaming Service).
• Ensure you have a properly formed HTTP "UserAgent" parameter. This is used extensively for metrics and analytics purposes.
• Provide a certain level of connectivity intelligence (e.g., connect to the correct stream type that the requesting device supports).

See below for details about the essential functionality of live streaming.

On-demand:

• Call an on-demand endpoint to receive VAST/DAAST ads.
• Display and report any events relative to VAST/DAAST.
• Connect to the file and play the file.
• Offer a user interface to allow “seeking” through the file when that option is possible.

Live Streaming

This section provides more details on the essential functionality for live streaming.

Connection and Playback

There are two slightly different methods to connect to a stream on the Triton Digital Streaming Network. URL entry points exist for different connectivity scenarios and uses, including:

• Live stream redirector
• Provisioning XML

These entry points are explained in more detail below.

Live Stream Redirector

For simplicity, this is the recommended way to connect to Triton Digital streams. This endpoint will always return as a URL redirection, so you don’t need extensive knowledge of the Triton Digital provisioning XML to make it work.

The details of how to build the URL to connect to your Live stream can be found in the Streaming Specification section on livestream redirect.

For example, if your station is KSAD using an AAC mount (“KSADAAC”) on HLS stream, your URL would be:

http://playerservices.streamtheworld.com/api/livestream-redirect/KSADAAC.m3u8 

Retries should be handled properly. If a streaming server is down, you can retry on the same URL using a delay mechanism. The player redirect service will randomly pick one of multiple servers in different data centers for every request.

Also refer to the Triton Digital Streaming Specification section on Connection Management for more information on how to handle re-connection.

For more information on HLS, refer to the Streaming Specification section on HLS.

Provisioning XML

Provisioning XML gives you the most control, as it makes extensive use of the custom Triton Digital SDK components, but also requires the most effort in terms of understanding the components and using them correctly. However, if you simply want to connect to a stream using HTTP Live Streaming (HLS), we recommend you use the Live Streaming Redirector method instead (see below).

The provisioning XML URL contains everything that is “known” about the station you are connecting to. If you follow the logic of provisioning you can always find a URL entry point in every format possible and available for that station. Your code can cycle through them or be specific to the appropriate method of connection. It also returns all the servers that have the connection point available.

This method is mainly used in cases where you need full control over the connection. For example, a single code base made in Xamarin or JAVA; the logic of what and where to connect is controlled by the platform discovery libraries from Xamarin or Java.

For the best results and failover mechanism, follow the Connection Management information in the Triton Digital Streaming Specification.

Ensure Compliance

Build your player to ensure compliance with the Triton Metrics requirements:

• Don’t allow two or more simultaneous connections (i.e., “double play”).
• Do not allow "pause" on live streaming. Use Stop and Start only. You can include a "Mute" button, but it must function the same as Stop – actually stopping the stream – and this should be clear to the listener. From a measurement perspective, Mute and Stop are the same.  
• Use a “backoff/retry” scheme when connecting, to avoid hitting the Triton Digital servers with too many connection requests. For more information, see the Triton Digital Streaming Specification section on Connection Management and the section on HTTP Live Streaming.

Metadata

You can use Shoutcast for metadata, but it is not widely used. A better option is sideband metadata (SBM). This is a secondary connection that provides different events in parallel with the stream, such as tracks listing for “now playing” display, and advertising events for ad insertion. Make sure your player has a handler that knows how to interpret these events.

A few notes:

• An ad event can contain a link to a VAST URL, which can bring in ad parameters such as banners, etc.
• The metadata timestamp in the live stream represents milliseconds since the stream was started. Sideband data is typically a few milliseconds later. You need to run a timer on the app that tracks time since connection. Events in metadata will contain timestamps indicating when the player should react to the event. It is important to be accurate for events involving ad insertion. If you’re not doing ad insertion then this timing doesn’t have to be so precise.
• Build your own VAST parser or use one that is available online, such as the IMA SDK from Google.
• Be sure to respect VAST principles. For example, make sure you report every impression, and that you trigger every URL.
• Do not be unnecessarily strict with the VAST parser. For example, do not reject VAST files that are of a different version than your parser; it should play VAST 2.0 or VAST 4.0 even if your parser is version 3.0.
• For more information, refer to the Triton Digital Streaming Specification section on sideband metadata.

Build Your URL (Parameters List)

The Streaming Specification section on Stream URL outlines the structure of the URL and the parameters that you can build into it. Available query parameters are listed here.

The most important parameters you should pass with the URL are:

• LSID.
• SBMID, which is used to correlate the stream with its associated metadata.
• Any targeting attributes. We recommend you pre-build these as much as possible before connecting to the stream.
• Any location attributes.

Remember that the more parameters you use, the more valuable your impressions can be.

User Agent

Web player user agent will automatically use the one provided by the browser, and it can’t be modified. However, developers may have control on their application user agent.  Build your player’s user agent in an intelligent way so that Triton analysts can detect and name your app or devices properly. If you need guidance on this, speak with a Triton Digital Solutions Specialist.

Connectivity Intelligence

Connection Management is explained in the Streaming Specification, here.

The diagram in that document is mostly applicable to the Provisioning XML method. It is simpler for the Live Stream Redirector method.

A few notes:

• Be prepared for disconnections and know what to do when there is a disconnection.
• Use the correct techniques for connections and disconnections.
• With the help of a buffer, your app/player can manage reconnections to make it almost seamless for the listener.