Configuration and Operational Requirements
Unless Client uses Service Provider’s Streaming and Delivery Services, Client shall either (a) implement the latest version of Service Provider’s Listener Tracking API, as provided to Client by Service Provider, or (b) allow Service Provider to collect logs from the Client's streaming servers or content delivery network (Log Collection).
The requirements described below apply, depending on the Client setup.
Log-collection
Log Type and HLS Requirements
This service only supports session logs, which need to characterize a human-listening session from initial play to the next pause/stop. It does not support HLS chunks and m3u8 log entries, and it does not re-assemble those in order to re-create session information. Therefore, the CDNs or publishers are responsible for providing session information even when doing HLS.
Log File Delivery and Frequency
Log files are pulled by Triton Digital from the publisher's FTP or SFTP (pickup point). Publishers are required to provide the needed credentials to obtain the log files.
Log files should reach the pickup point at least daily, but can be more frequent, especially if the logs are larger and in multiple chunks. Triton Digital expects to receive session information within four days of the beginning of the session. If the session log is received after this delay, it will not be counted in the aggregated metrics.
File Name
Log files should be uniquely named, with the date as part of the filename. Each named file should arrive at the pickup location when the log is complete (rather than opening up FTP to the actual logging folder where files are being actively written), and each unique filename will be retrieved/processed once. An example of a good filename for this purpose is: MSLT20170830-00.tsv.gz, where 20170830 is the date, and -00 is a suffix, if needed, for the hour, file-number on that day, or some other sequencing/unique identifying value.
For efficiency purposes, each log file should be compressed in a ".gz" single-file archive.
File Format
Log files should be in one of the following formats:
- Formatted in the standard output of the streaming server. The default access-log output of most current audio streaming services is often usable with no special changes to configuration.
- Formatted per the W3C extended log format (https://www.w3.org/TR/WD-logfile-960221.html). This format is commonly used for streaming server output. It is basically a tab- or space-delimited file with a header that identifies field names for each column in the data.
- Formatted as tab-separated values (tsv). Details: Tab character (As \t or 0x09). Line Ending (\n or 0x0A). The # character for a commented line. Header line is recommended but optional. If this format is used, please contact your Triton Digital Client Success Manager with details on your planned output format/fields so that we can ensure it matches with a log parsing scheme.
Required and Optional Fields in the Log Lines
| Required Fields (LC/LT) | Description |
|---|---|
| Remote host IP address (or hostname if DNS lookups are enabled) of client. |
| Date at which transaction is completed. Format is YYYY-MM-DD. |
| The timestamp of the session end. Format is HH:MM:SS where HH is the hour in 24 hour format. |
| Numeric, up to nine digits. This is the duration of the listening session, in integer seconds. |
| Up to 2048 characters complete URI (or URL). This value should be populated with a unique publishing-point (URI) so the record can be applied to that station in our system. In other words, a part of this field will be used as the key to match with a station in Triton Digital's database. |
| Contents of "User-Agent" HTTP header. This user-agent HTTP header contains a characteristic string that allows network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent. |
Optional Fields | Description |
autoplay | Flag that indicates if the session has been initiated from a player auto-play. Possible values are autoplay=0 (not initiated via auto-play) and autoplay=1 (initiated via auto-play). Auto-play of audio content is strongly discouraged since in some cases, auto-played streams are not audible as the volume may be muted while the stream continues to be active. Triton Digital recommends that any initiation of audio content playback is determined by an overt user gesture, such as a tap or a click. |
| The address of the previous web page from which a link to the currently requested page was followed. |
| The timestamp of the session start. Format is HH:MM:SS. |
| Station Identifier where the listener has initiated a listening session. If this value is present, it may substitute the URI as the key to match with a station in the Triton Digital database. |
| A unique visitor ID that can be used to identify a listener and must come from a listener registration mechanism. |
| The Triton Digital LSID (a.k.a UUID). This is the App/Cookie/Advertising ID as presented in the Listener ID Management topic of the Advertising Technical Specification. Typically, on a mobile device, this is a Google gaid or Apple idfa, or if not available, an application-generated ID. On desktop, it should be a cookie ID. |
| Listener's gender (M or F or U). U can be used for "other" or "unknown" gender. |
| Listener's year of birth, using the YYYY format. |
| Listener's age. |
| Listener's ZIP code (5 digits) or postal code (alpha-numeric, no space). |
| Flag that indicates if the listening session can receive advertising. Possible values are 0 and 1. Sending 0 indicates the session cannot receive advertising. |
| Extra property used to specify on which device the session is initiated. Triton Digital can provide a non-exhaustive list of available devices, but clients may extend that list for their own usage. |
| Extra property that can be used to produce aggregation that shows on which distributor/partner the session has been initiated. For example, Publisher A shares their stream on Distributor/Partner B, so the Distributor property is "B." |
| Extra property that can be used to produce aggregation that shows the publisher of the stream. For example, Publisher A shares their stream on Partner B, so the ss property is "A." This is rarely used, since logs are typically produced by the publisher. |
| Extra property used to specify on which player the session is initiated. Triton Digital can provide a non-exhaustive list of all available players, but clients may extend that list for their own usage. |
QUERY PARAMS | Any or all other URI Query param strings may be provided for potential future usage. |
Customs / Others | Any other parameters sent will be ignored by our systems. |
Listener Tracking-based
For Listener Tracking information, see the Triton Digital Measurement Guide.
Equipment Change
Client shall notify Service Provider prior to any change made to Client Equipment (defined as any and all hardware, software, network, infrastructure and any other type of equipment which is used in connection with the Services, whether owned by Client or a third-party, and which is not under the direct control of Service Provider) or processes that may affect, directly or indirectly, the measurement output including, without limitation, changes in Client’s content delivery network, Raw Data or listener tracking implementation. Notwithstanding the notification provisions of the Agreement, such notification shall be made by way of email to measurement@tritondigital.com.
Web Player and Application Guidelines for Webcast Metrics
Web player and application guidelines are described in the Triton Digital Measurement Guide. Topics include:
- Stop vs. Pause
- Auto-play
- Start and Stop at the Right Moment
- Muted/Audibility Requirement
- Direct Links on Web Browsers
- Long Sessions
- Use of Visitor (Listener) ID for LT Methodology
- Cache-busting Required for LT Methodology
- HTML5 Consideration: Pre-load/Pre-fetch
- HTML5 Consideration: Stopping the Audio
Real-time Statistics
As part of our basic offering we allow stations to get real-time reports of their live listeners for every five minute data point of every day. To accumulate these statistics, real-time audience data must be provided by the CDN using a publicly accessible XML feed that displays the current listener count for each stream that is hosted for a particular radio station.
This requirement is already met if you use Triton Digital as your CDN, and real-time statistics are included with Listener Tracking-based WCM.