# Custom Analytics Integration on iOS Video analytics provide tremendous insights into your user's QoE, bring extra business intelligence and enhance decision-making. There are a wide selection of analytics systems in the current landscape (e.g. Google Analytics, Conviva, ...), often with their own focus, expertise and value. What most video analytics systems have in common is that their insights (partly) originate from video events: * `play` event: a user clicks the play button, or resumes playback after a pause * `fullscreen` event: a user goes fullscreen on their device * `quality` change event: the video quality switches from a lower resolution to a higher one * `waiting` event: the video is stalled and unable to continue playback for some time * ... To access these video events, and forward them to a video analytics system, an application developer must hook into the video player API. This guide explains the role of the THEOplayer API. Additionally, it explains how to do a custom integration with an analytics system, with Google Analytics as a sample case. This guide should be useful when THEOplayer doesn't have an existing sample integration with a specific (commercial) video analytics service, or when you want to fully control the data flow. Keep in mind that Google Analytics is not the only analytics system out there. The APIs and concepts that we'll discuss are relevant for all analytics systems. For example, you can easily swap out the Google Analytics example with something like [Nielsen](https://www.nielsen.com/solutions/audience-measurement/) or [Youbora](https://npaw.com/) (NPAW), or even your own custom analytics back-end. ## Prerequisites There are two prerequisites in order to continue with this guide: 1. You have a THEOplayer license. You can grab a license at . 2. You have some basic knowledge on how to use THEOplayer, and can navigate comfortably through [the API](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios) to find relevant events. Refer to our [getting started guide](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/getting-started/sdks/ios/getting-started.md) before advancing to the code samples. ## API You can access the video data through the THEOplayer API. Through the API, you can subscribe to events, and attach a callback. For example, when the `ended` event is triggered (meaning: someone completely watched the video), your callback could be that when this happens, you do a request to a remote video analytics service. Events are organized across interfaces and subinterfaces, as illustrated by the image below. For example, the player contains general video player events like `play`, `pause` and `ended`. The ads interface contains events related to advertisements, like `adbreakbegin` and `adend`. ![THEOplayer API Interfaces and Events](/pr-860/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events") When creating a custom analytics implementation, you must familiarize yourself with the relevant interfaces and events. Below is an (incomplete) list of some common interfaces and their event maps. * [Player](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios/Structs/PlayerEventTypes): general video events, like a play, a pause, and so on. * [Ads](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios/Ads%20Events): to detect when an ad starts and stops. * [AudioTrackList](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios/Structs/AudioTrackListEventTypes): to detect when a new audio track is added, or when another audio track becomes active. * [TextTrackList](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes): comparable to AudioTrackList, but for subtitles, closed captions and metadata (e.g. id3, emsg, EventStream, EXT-X-DATERANGE). * Cast: [AirPlay](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios/Structs/AirPlayEventTypes) and [Chromecast](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios/Structs/ChromecastEventTypes) events. Video quality events are unavailable on iOS due to Apple limitations. Note that maintaining the above list manually is unfortunately a no-go because our interfaces evolve. This means that you should research your events through our [API reference](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios). When doing a custom analytics integration, you should also check our articles on [error handling](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/how-to-guides/ios/miscellaneous/error/introduction.md). ### Video analytics metrics and events Let's discuss some popular metrics, and how you could track them with video player events. Plays (or Impressions). This metric represents the amount of plays. You can calculate this event by identifying the first `playing` event after every `sourcechange` event. Video Startup Time (or Time-to-First-Frame or Join Latency). This metric represents the time it takes your video to start. You can calculate this event by calculating the difference between the timestamps of the first `playing` and the first `play` event after every `sourcechange` event. Seek Time (or Seek Latency). This metric represents the time it takes for your video to resume when you scrub to another position. You can calculate this event by calculating the difference between the timestamps of the `seeking` and the `seeked` event. Watch Time. This metric represents how much time is spent watching content by your viewers. You calculate this value by tracking the `playing` event, and halting it when the `waiting`, `pause`, `ended` or `error` event occurs. Rebuffer Ratio (or Stalls). This metric represents how often the viewer is watching the "spinner icon" versus the actual video. This metric is closely related to the Watch Time. You can calculate this event by tracking the `waiting` event, which is triggered when the video starts to stall, and the `playing` event. Average Bitrate. This metric represents the average video quality that your viewers are watching. You can calculate this metric by tracking the `activequalitychanged` event of the active video track. Average % Complete (or Watched Ratio). This metric represents the relative completion rate of your videos. This metric is related to the Watch Time, and related in a similar fashion. You could also use the player's `duration` to determine the length of the asset. Exit Before Video Start. This metric represents how often your viewers aren't able to start the video, even though they had the intent to watch it. You can calculate this metric by tracking the first `play` event, and it never getting to the `playing` event. Video Playback Failure. This metric represents how often your viewers have a problem with playback once a video starts. You can calculate this metric by tracking the `error` event after the first `playing` event. Note that these proposed calculations are only loosely formulated to help you understand the relationship between video metrics and a video player API. When talking about metrics, you often apply dimensions or filters to a metric. For example, when talking about the "Plays" metric (see above), the base metric would apply to all logs throughout all time. When analyzing your data, you might want to apply a filter (or dimension), such time (to consider all "Plays" for a specific period of time), asset (to research a specific asset), user (to check a specific user's activity), and so on. It is up to you (or your commercial analytics service) to associate certain dimensions with a raw video player event. ### Session management It's important to note that THEOplayer doesn't associate a user ID or session ID with an event. (This is pretty normal, because THEOplayer is a client-side video player library. It's not aware of your "back-end" "CMS", "users" or "sessions".) When you are implementing an analytics service, you usually want to associate a session or user with an event when forwarding the event to your remote analytics database. As an app developer, it is your responsibility to do this association. ## Integrating Google Analytics Refer to Google Analytics' documentation at if you're interested in integrating Google Analytics. Similar to the Web SDK, developers would subscribe to events and properties emitted by THEOplayer and create a custom mapping to the Google Analytics library. ## Conclusion A custom analytics integration gives you full control over your code, and the data you want to submit to your analytics system. This data is exposed through the THEOplayer API, and allows you to subscribe to events such as the start of an ad, or a direction change event in 360/VR playback. Extra resources: 1. [THEOplayer API](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/v11/api-reference/ios) 2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-860/theoplayer/getting-started/sdks/ios/getting-started.md)