Managing messaging
Overview
The OPF Messaging Service supports a number of use cases, including both automated and operator-initiated scenarios.
It uses a combination of:
Standard third-party cloud-based services – Google Firebase, Amazon Simple Notification System (SNS), Amazon Device Messaging, and AWS IoT Core
Standard client library implementations
This enables notifications to be sent to various types of devices (iOS, Android, FireTV, and Smart TV (Tizen and webOS) devices).
The following diagram shows the main components involved in messaging and the primary interfaces between them:
The OPF Messaging Service consists of:
Open Device Messaging (ODM) – handles registration of devices with DMM. It does this automatically – when a client app calls ODM to register the device, ODM automatically registers it with DMM.
Device Messaging Manager (DMM) – handles creation and management of topics, subscribing devices to topics, and sending notifications to topics or devices.
The Message Management section in Operator Console – allows you to manage topics and send messages. See Message Management.
OpenTV Platform uses this service itself to notify clients of metadata changes (such as EPG schedule changes). See Metadata change alerts.
Supported messaging use cases
Use case | Description | Generating source | Target |
|---|---|---|---|
EPG updates | EPG metadata updates | Automatically generated by OPF | All devices registered to the OPF global topic |
Entitlement change notification | Notification as a result of an entitlement change (add/delete/update) to an account in OPF (RMG) | Automatically generated by OPF | All devices within a specific account whose entitlements have changed |
Emergency Alert System (EAS) alert (US only) | Regulatory emergency alert message | EAS Platform integrated via OPF-DMM interface | All devices within an account that matches the specified EAS FIPS code |
General notification | Free form message, generally used for marketing or general notices / information | Operator platform via OPF-DMM interface Operator via Operator Console Messaging screen | All devices registered to the targeted topic |
Not all use cases are relevant or configured in every deployment.
Message targeting
OPF messaging supports three routes for message targeting:
Targeting a specific device
Targeting all devices that are registered to a specific topic
Targeting all devices (by sending a message to the
GlobalTopicForAllDevicestopic that all devices are registered to)
It is also possible to target all the devices that belong to a specific account by first getting all the devices that belong to the account and then sending a message to each one separately,
Message topics
Messaging is organised around the concept of topics. Once a device is registered with the service, you can subscribe it to any of the topics that have been defined.
There is a default topic (called GlobalTopicForAllDevices) to which all devices are automatically subscribed.
You can also create any number of ad hoc topics and subscribe devices to them as required.
When you send a message to a topic, the message is sent to all the devices that are subscribed to the topic.
You can create topics:
Via a DMM API call – see:
In Operator Console (OpCon) – see Create topics
Message format
Automatically-generated messages
There are two types of messages that are automatically generated by OPF:
Entitlement change notification
EPG updates
Each type of message has its own specific format, which cannot be changed.
Client applications are responsible for interpreting these messages and processing them accordingly.
General notifications
For general notifications that you (the operator) initiate, the message format is freeform.
When sending a notification via a DMM API call, the contents of the message are defined by the entity that is calling the API.
When sending a notification via OpCon, the UI has the following fields:
Event Type (free text)
Message Title (free text)
Message Body (free text)
Message Expiration (date picker)
The client receives the message title and message body as structured attributes.
The event type is used only for internal tracking in OPF.
See Handling messages received from OpenTV Platform for detailed information.
Message TTL/expiry
Every message is published with a time to live (TTL) / expiry date and time, which determines how long the message is available through the messaging services that are used to deliver the message to clients.
This is set as follows:
Via a DMM API call – as part of the API request
In OpCon – in the Message Expiration date picker when sending a message
Client processing of messages
Client applications are expected to process the messages that they receive and react accordingly, as explained in the following table:
Use case | Client action |
|---|---|
EPG update | Update EPG metadata accordingly, introducing appropriate jitter to minimise peak loading and also utilising cache management to take advantage of cached responses. |
Entitlement change notification | Update the cached entitlements. The notification includes all the information required to do this without having to make any additional calls to RMG. |
Emergency Alert Sytem (EAS) alert (US only) | Tune to the indicated channel and/or display information as dictated by the message and EAS standard. See Emergency Alert System (EAS) integration. |
General notification | Defined on per deployment basis – the nominal use case would be to display a message with either an automatic “clear from screen” or await user interaction. |
See Handling messages received from OpenTV Platform in the Client integration guide.
Prerequisites
Google Firebase setup
Messaging uses Google Firebase. You must set up the Google Firebase instance so that it belongs to you and so that you have access to Firebase Analytics. See Setting up Google Firebase.
Registering devices with Firebase, Amazon Device Messaging, or AWS IoT Core
Before a device registers with ODM, it must register with Firebase, Amazon Device Messaging, or AWS IoT Core, depending on the type of device:
iOS and Android devices must register with Firebase.
Amazon (that is, FireTV) devices must register with Amazon Device Messaging.
Tizen and webOS Smart TVs must register with AWS IoT Core.
When a device registers with one of these services, it will receive a token. It must pass this token to Open Device Messaging (ODM) when registering with it.
After a session ends or the device logs out, it will need to refresh this token and call ODM again with the new token.
Devices that register with AWS IoT Core (that is, webOS and Tizen Smart TVs) should only stay connected to IoT when they are in the foreground. They should disconnect when backgrounded.
Failure to do so will result in increased AWS charges.
Specifying the messaging platform at first-time sign-on
When a device signs on, it must provide device details. These details include the message platform that it uses. See deviceInformation.msgPlatform in the table in First time and n-th time sign on.
Supported actions
The following actions are supported:
Note that all of the DMM endpoints used in these use cases are OPERATOR endpoints – they cannot and should not be called from a client application.
The Registering a device and Unregistering a device use cases use ODM and IAS endpoints that are specifically for client applications.
Message length
Maximum message length depends on the device, where the notification is displayed (that is, on the lock screen or in the notification centre/drawer), and the device orientation.
Please refer to device manufacturers' and the relevant OS documentation for specific limits.
Limitations
You are responsible for handling the language of notifications that you send. OpenTV Platform does not have an automated mechanism to select the message language based on the device’s language settings.
Currently, no provision/API is available in OpenTV Platform to unregister a device and to stop receiving notifications. This means that a device will continue to get notifications even after the app has been uninstalled.
OpenTV Platform does not automatically purge device registrations.