Client integration guide [NEW]

This new version of the client integration guide is a work in progress.

For existing use case documentation, see the Client integration guide.

Overview

This guide offers essential details and best practices for integrating a client application with OpenTV Platform (OPF), NAGRAVISION's SaaS video platform. It is intended for development teams, architects, and integration teams looking to understand the basics of system integration.

Since this guide is generic, specific details like API parameters may vary between releases. For detailed information, refer to the API documentation.

What are we integrating?

OPF is a cloud-based SaaS solution built on versioned microservices, API gateways, and native cloud resources featuring a specific set of APIs accessed with necessary Authorization for client integration. It is typically deployed in a manner tailored to each customer in the aspects of geographic, feature-level configuration, and secrets. The provider of the client applications is expected to hold the required client-side configuration specific to the respective devices.

Please reach out to your integration contact to get the relevant details of your deployment.

Aspects of integration

API versioning

As you integrate with the platform, you will be working with the versions of services indicated in the path. For example, /ias/v3/token. The general guidance is stay on the latest API version that is available in the deployment. When a new API version is published, the client integrators will be made aware of the change. The process to adapt to a service version change can be planned as per the customer schedule and deployment.

The base paths of the services inclusive of versions is expected to be bundled with the client. The method is at the integrator's discretion.

Authorisation

Client applications convert user credentials like username/password or a managed identifier into OAuth tokens—Access Tokens and Refresh Tokens. These JWT tokens, with selective disclosure of customer details managed by NAGRAVISION, can be stored persistently in the application’s local storage for availability across reboots. Token exchanges are recommended to utilise the Authorization header for enhanced security where supported for security reasons.

See Identity Authentication Service (IAS) API documentation.

Token expiry

In application cold start or resume lifecycle actions, the token needs to be checked before using in Authorization to avoid unnecessary 403 error HTTP traffic.

Third-party identity

When user authentication is required to access a customer's identity infrastructure or a third party, the login mechanism is recommended to be abstracted behind a plugin-based service provided by OpenTV Platform’s Authentication Gateway Service (AGS). This approach simplifies the process, resulting in a pair of access and refresh tokens from the login sequence, rather than necessitating multiple server roundtrips from the application.

See Authentication Gateway Service (AGS) API documentation.

Decoding tokens

The token holds valid information about a login session and an account at the time of issue. All data within the token can also be retrieved via the respective service endpoints. For critical references about a user's account, it is recommended to use these service endpoints due to the potential staleness of token information, especially in environments where account changes may occur through operators or CRM systems.

Configuration

The configuration of an application can be made remotely adjustable. While it is not mandatory, this is considered a best practice.

Devices

Types

The main difference in providing service across various devices lies in the operator's operational model. Open devices generally allow app downloads from the relevant application store, while operators may offer managed devices with pre-installed apps.

Upon first sign-in, a client app can report device parameters – such as make, model, and OS version – within privacy limits. This improves features like messaging and personalises user experiences. The app is expected to:

• Interact with standard OS interfaces to read metadata.

• Provide device capabilities (e.g., codecs, OS version) to tailor content.

• Enable device-specific consumption limits.

• Offer device-specific entitlements for certain content.

Personalisation

For a seamless experience across all devices, avoid using local storage for personalisation features like continue watching, profiles, recommendations, favourites, etc. It is recommended to always interact with service endpoints for these purposes.

See Recommendations Façade.

Recommendations

Where applicable to the deployment, integrated recommendation engines will profile users' usage of the service, based on their privacy settings . This includes content viewed, favourited, purchased, etc. by individual users as well as clusters of users, providing both deployment-wide and personalised recommendations.

To improve content recommendations, keep the engine updated with the latest user activity trends while respecting privacy and consent.

See User Activity Vault (UAV) API documentation.

First use

During onboarding, the app should collect user inputs such as language preferences, parental rating settings, and user profiles. These inputs should be stored on various service endpoints, as they are essential for business logic, such as filtering content based on parental rating age settings. It is not recommended to store these values locally on the app.

PINs

Where appropriate, the app must check if the user has set a PIN or prompt to create one during first use. PINs may be required for purchases, parental ratings, etc., depending on operator requirements. Except in cases like offline mode, the app should validate the PIN with the service API.

See Account and Device Manager (ADM) API documentation.

L10N and I18N

The following aspects of the application must be addressed, considering both the operator's requirements and geographical factors:

Content and metadata

OPF integrates various types of content such as live variants (including Start Over and Catch Up), on-demand, series, and long-term catch-up (LTCU). For playback, URLs are expected to be retrieved from the service metadata APIs, apart from the Start Over feature, where a template is provided for the application to complete according to the start time of the event starting over on the service.

See Metadata Server (MDS) API Documentation.

Types

The cacheability requirements vary between different types of content. Typically, services and programs require persistence or cache ability due to their usage across application screens. For example, a service call response cache helps with channel logo, name, and playback URL across the app for tuning to a service or presentation.

Persistence

Choosing to use persistence is an intentional decision that depends on the deployment requirements and the capabilities of the host. For example, managing EPG metadata for several days in advance and retrospectively can be accomplished in one of the two ways outlined below.

Minimal upfront cache

In this method, we download a time slice of data, say 15 hours, split between nine hours forward and six hours backwards for all services to be used everywhere in the app in different screens. When a user goes outside this block in a user interface via navigation, for example, in the guide, we need to download more data sliced by time window to fill the interface.

The advantage of this approach is that it will have base line fetch that is predictable traffic, and the rest of the calls are user driven.  

Background bulk fetch

In this method we should perform background fetching and periodic updates. This is useful for scenarios like STB devices combining broadcast and OTT EPG or OTT EPG with multicast stream consumption.

This approach is advantageous because, when EPG update is infrequent, the application remains self-sufficient.

Discovery

For screens displaying an n x m grid of content, an app should retrieve sufficient data to cover the viewport plus a buffer. For instance, this is applicable for a promotions screen organised in rows. To load the content below the fold, the content will be retrieved from the service again as the user navigates either horizontally or vertically.

See Content Builder API documentation and Content Delivery API documentation.

Rails

A client application must follow the following process:

1. Get each template with a list of rail IDs.

2. Load the rails dynamically:

   1. Load 150% of the rails required to populate the screen as per first load.

   2. Load additional rails on demand as the client scrolls.

3. Obey the caching headers as per the response object.

See Best practices – rails.

N-1 render

Screens designed for discovery need to render instantly and be personalised. To avoid delays, build an API cache on the device that displays cached responses and syncs with the server. This method renders quickly on the screen and handles any API latencies.

Search

The search integration path is set at deployment time. Some deployments require integration with the Search API (and optionally Search Suggestions and Search History), while others use a templated search preconfigured on the backend, requiring the app to integrate only with the template itself. This decision is fixed and cannot be changed by the app.

The search functionality enables users to quickly find content of interest. The platform offers a robust search experience, structured into three key areas: Content Search, Suggestions, and History.

Content search

The core search process requires only a search term provided by the app. By default, searches attempt to match against the following fields:

• Content title

• Actors

• Channel name

• Channel number

• Category/genre/sub-genre

• Year

• Series

• Season

Matches against broader metadata, such as descriptions, are not supported.

The API also supports complex queries, allowing for refined control over search results while ensuring relevance to the requesting device. For a full list of supported parameters, refer to the API documentation:

See Search Facade API documentation.

Best practices for search requests

To optimize search performance and accuracy, follow these best practices:

• Use paginated results

  • Utilise limit and page parameters.

  • Example:

    • limit=10&page=1 (initial search)

    • limit=10&page=n (for additional pages, on demand/in background)

• Explicitly record search history

  • Use the recordHistory parameter.

  • Example:
    recordHistory=true or recordHistory=false

• Specify the requesting device

  • Use the device parameter.

  • Example:
    device=AndroidTV

• Use quotation marks for exact matches

  • If precision is required, enclose terms in quotes.

  • Example:

    • q="Harry Potter" ensures an exact match.

    • q="Hrry Potter" may yield no results, whereas q=Harry Potter or q=Hrry Potter increases the likelihood of a match.

Search suggestions

The search suggestion feature provides a type-ahead experience, displaying between one and several relevant full-value matches based on the user’s partially entered text. As the user continues typing, the suggestions become more precise, aiming to predict the intended search result before the majority of the text is entered.

This functionality offers several key benefits:

• Faster search completion – especially useful for longer content titles.

• Accurate text matching – reduces the risk of spelling errors.

• Content-aware results – suggestions are generated from available metadata, ensuring only relevant matches with no false positives.

Search suggestions support broadly the same parameters as the core search – refer to the API documentation for more information.

Search history

Search history functionality allows clients to retrieve a list of previously entered search terms, providing a seamless way for users to revisit past searches. Recording search history is optional and can be controlled via the recordHistory parameter. When enabled, the client can request up to n history entries, ensuring a flexible and user-centric experience. For more details, refer to the API documentation.

Search template

The search template follows standard rails patterns, enabling search functionality to be configured on the back-end rather than built directly into the application. This approach allows operators to modify the search experience dynamically, with changes reflected in the app without requiring a new release.

The templated search can be configured within rails to support:

• Standard search

• Custom parameters and filters

• Different search engines, including:

  • Standard search

  • Personalised search (e.g., via a recommendation engine)

Since a search template is simply another variation of a standard rails template, it can be seamlessly combined with other rail types. Additional rails do not need to be search-based, so the template could contain promotional banners, recommendations alongside/intermixed with the search rails, allowing for flexible content presentation.

Playback

The URL for playback will be filtered based on the decryption module present on the device, such as Widevine, FairPlay, or PlayReady. The filter strings for the specific technical device types can be obtained from the SaaS operations team for the project.

In an OTT environment, playback of content from the transcoder involves downloading chunk from the CDN, as well as license and CDN fetching with security requirements for encrypted content. When the playback sequence starts, multiple layers from CDM to the HTTP protocol stack will be active. It is not recommended to perform render-intensive operations simultaneously, as this can affect playback performance.

See Identity Authentication Service (IAS) API documentation.

Non-OTT and hybrid

On a hybrid DVB + OTT device, live TV channels should be consumed based on the designated sourcePreference parameter, which indicates the intended primary source. If DVB is preferred and available, the device should tune to the broadcast signal to ensure optimal video quality, reduced latency, and efficient bandwidth usage. Conversely, if OTT is the preferred source or DVB is unavailable, the device should stream the channel via OTT. The selected source should integrate seamlessly with the channel list and electronic program guide (EPG).

Whenever a timeshift activity – such as play, pause, rewind, or fast forward – is initiated on a hybrid channel, assuming the channel supports timeshift and the user is authorised to carry out timeshift activities, the device must switch from the DVB source to the designated OTT startover (SO) stream. This transition enables on-demand playback while maintaining continuity of the viewing experience. The switch should be seamless, minimizing buffering or disruption, with the OTT stream aligned as closely as possible to the original broadcast to ensure a smooth user experience.

When the user pauses or rewinds content, the inherent latency of OTT streaming may cause the requested segment to be unavailable immediately, as the OTT stream might not have buffered that segment yet. The device may need to buffer the paused content, potentially causing a short delay before playback can resume. If the content is not yet available in the OTT stream, the device may temporarily switch back to the DVB stream to ensure the user can continue watching without interruption until the OTT stream catches up.

Similarly, a user fast-forwarding to the end of the SO stream will result in an unavoidable jump forward when returning to the live broadcast. Since OTT playback lags behind DVB due to encoding and network delays, the transition back to live will cause a noticeable time skip. To minimise disruption, the device can implement smooth transitions, such as displaying a brief message (e.g., "Returning to live"), but some degree of abruptness is unavoidable when resynchronizing with the true live feed.

Transcoder

An application client should not worry about the transcoder, but must be aware of the environment, as start and end time formats vary between providers for start over and catch-up URLs. Clients should account for a single transcoder per deployment customer, although deployments might have a mix; therefore, flexibility in design is required.

See Metadata Server (MDS) API Documentation (for start-over and catch-up URL).

Products and entitlements

The purchasable entities on the business services platform will be subscription, transaction, or capability-based. A client integrator needs to logically link subscriptions and transactions with content and capabilities, and features at a high level. Content can be linked to multiple other contents, and they could have different start and end times of availability. The user should be declared as subscribed to content based on that information.

See Rights Manager (RMG) API documentation.

Observability

The client integrator should offer app insights for analytics or crisis debugging. The SaaS platform logs events like generic, playback, or app failures using the Data Warehouse (DWH) infrastructure when needed.

Application version management

Multiple app versions can be live at once, leading to unpredictable behavior in production. Events must link to the correct version to determine fragmentation. To aid in migration, the client integrator should be able to force an upgrade when user action is required.

Reporting errors

Operations require detailed error information for a production instance. The choice of tool is up to the integrator based on their tech stack.

Exponential fallback

Failure of critical services such as IAS, notifications, and RMG entitlements will directly impact critical or regulatory requirements for deployment. Therefore, an express fallback must be implemented for accepted error codes.

Messaging

A client app may need to be notified asychronously from the business platform backend to support use cases such as EAS (Emergency Alert System), back-end metadata updates, TVOD purchase notifications, etc.

To provide this capability, the OpenTV business platform back-end supports a head-end messaging infrastructure that is pre-integrated with Firebase and AWS IOT Core to meet the different capabilities of client devices. The operator can send push IP messages via the back-end HE to message a group of devices or target a specific device.

For use case, such as EAS, the operator may push IP messages to a group of devices located in a certain geographic area. For metadata update, the operator may update certain program/event information, which would require the client app to be notified so that it call pull the latest metadata events from MDS (business platform service) to show an updated UI.

The client application can use the Firebase SDK for Android and iOS devices and the AWS IOT Core SDK for Smart TVs (Tizen and webOS). For messaging to work with the business platform, the client app must make use of the Open Device Messaging (ODM) API by passing certain messaging-specific credentials (FCM token or IOT client ID) along with business platform credentials (access token, device ID).