Messages

Overview

The Messaging Service allows you to send notifications to various types of devices (iOS, Android, FireTV, and Smart TV (Tizen and webOS) devices). It consists of two modules:

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.

Messaging is organised around the concept of topics. Once a device is registered with the service, you can subscribe it to various topics that you have defined. There is also a default topic (called GlobalTopicForAllDevices) to which all devices are automatically subscribed.

You can send messages to all the devices that are subscribed to a particular topic or to individual devices.

Messaging uses Google Firebase, Amazon Simple Notification System (SNS), Amazon Device Messaging, and AWS IoT Core, which together allow reliable sending of notifications to iOS, Android, FireTV, and Smart TV devices.

OpenTV Video Platform uses this service itself to notify clients of metadata changes (such as EPG schedule changes). See Metadata change alerts.

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.

Supported use cases

The following use cases are supported:

Unregistering a device

Creating a topic without subscribing devices to it

Unsubscribing devices from a topic

Updating the details of a topic

Deleting a topic

Getting all the topics that a device is subscribed to

Getting all topics

Getting all devices that are subscribed to a topic

Getting all devices

Sending a notification to all devices

Sending a notification to a specific device

Sending a message to all devices subscribed to a topic

Sending a notification to all devices that belong to an account

Subscribing devices to a topic

Creating a topic and subscribing devices to it

Registering a device

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, as explained in the tables in the following subsections.

iOS

Device	Display	Lock screen – portrait	Lock screen – landscape	Notification Center	Banner style	Alert view
iPhone 6/6S/7 Plus	5.5 in (140 mm) 1920x1080 px at 401 ppi	156 chars	N/A	156 chars	98 chars	Displayed 1283 chars, scroll for more
iPhone 6/6S/7	4.7 in (120 mm) 1334x750 px at 326 ppi	148 chars	N/A	148 chars	89 chars	Displayed 1217 chars, scroll for more
iPhone 5/5C/5S iPod touch 5th/6th gen	4 in (100 mm) 1136x640 px at 326 ppi	119 chars	N/A	119 chars	74 chars	1013 chars (no scroll)
iPhone 4/4S iPod touch 4th gen (A1367)	3.5 in (89 mm) 960x640 px at 326 ppi	114 chars	N/A	166 chars	43 chars	153 chars (no scroll)
iPad Mini touch 1st gen (A1432)	7.9 in (200 mm) 1024x768 px at 163 ppi	211 chars	220 chars	229 chars	124 chars	Portrait: 1957 chars, landscape: 1417 chars

Android

Device	Display	Lock screen – portrait	Lock screen – landscape	Notification drawer DefaultNotification Big Text Style	Notification drawer SystemNotification
Nexus 4 phone	4.7 in (120 mm) 768x1280 px at 320 ppi	40 chars	N/A	482 chars	40 chars
Nexus 5 phone	4.95 in (126 mm) 1080x1920 px at 445 ppi	37 chars	N/A	444 chars	37 chars
Nexus 6 phone	5.96 in (151 mm) 1440x2560 px at 493 ppi	37 chars	N/A	444 chars	37 chars
Nexus 5X phone	5.2 in (130 mm) 1080x1920 px at 423 ppi	46 chars	N/A	562 chars	46 chars
Nexus 6P phone	5.7 in (140 mm) 1440x2560 px at 518 ppi	37 chars	N/A	444 chars	37 chars
Nexus 7 tablet 2013 version	7.02 (178 mm) 1920x1200 px at 323 pp	42 chars	N/A	509 chars	42 chars
Nexus 9 tablet	8.9 in (230 mm) 2048x1536 px at 287 ppi	44 chars	44 chars	536 chars	44 chars

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.