Message UI is an alternative to InfoBar UI on Android. It provides a set of APIs and a consistent, ephemeral and trustworthy UI with various lifecycles and priorities.
Each message should include at least 3 properties: title, primary icon and primary button text.
Each message will automatically be displayed, hidden and dismissed according to given scope (see details below) and can be dismissed automatically or manually. By default, each message will be automatically dismissed after around 10s after it is displayed. The timer will be reset if the text or icon on the UI is changed or if the Message is re-shown. Also, users can dismiss the message by swiping the UI upwards, leftwards and rightwards. The feature clients can also manually dismiss the message through provided APIs if necessary.
You need to do the following things to enable your message UI, all described in detail below.
You need to create a MessageIdentifier
that represents your Message UI, which distinguishes it from other message UIs and enables some feature-specific metrics to be recorded.
The MessageIdentifier is defined as an enum
and a string, which should be appended in following files (you can refer to this CL as an example):
components/messages/android/message_enums.h
[1]tools/metrics/histograms/enums.xml
[1]tools/metrics/histograms/metadata/android/histograms.xml
[1]components/messages/android/java/src/org/chromium/components/messages/MessagesMetrics.java
[1]All available model properties are defined in components/messages/android/…/MessageBannerProperties.java
Only some of them are required:
The rest are optional, but some of those are very commonly used:
You can refer to this CL as an example on the Java side and this CL as an example on the Native side.
Some other, less commonly used properties are:
After the model is defined and ready to be displayed, it should be enqueued by calling MessageDispatcher#enqueueMessage and providing the model, scope, and priority.
MessageDispatcher is per-window object. In Java, use MessageDispatcherProvider#from to get a dispatcher available in the current window, which can be null if native initialization is not finished yet. In C++, use messages::MessageDispatcherBridge::Get() instead.
Message scope can also be seen as the life cycle of a message UI. It pre-defines when and where messages should be displayed and dismissed. There are 3 scopes in total (components/messages/android/message_enums.h):
There are two types of priority: urgent (a.k.a high) and normal (a.k.a low).
Urgent messages will be displayed ASAP, in spite of enqueued messages of normal properties. Urgent should only be used when the message is so important that you want users to take an action ASAP, such as a serious security risk found on the page the user is visiting. Otherwise, use normal in most cases.
As explained in Overview, by default, the message will be dismissed in the following cases:
In addition, messages can be dismissed by feature client code so that the message won’t be displayed any more. Use MessageDispatcher#dismissMessage to dismiss the message. The dismiss callback will still be triggered.
In native, MessageDispatcherBridge#EnqueueMessage will return a MessageWrapper object. The feature client is responsible for managing it. We recommend dismissing the message manually if the MessageWrapper object is still alive when the owner of the MessageWrapper object is destroyed.
On the Java side, components/messages/android/test/…/messages/MessagesTestHelper.java is available to get all current enqueued messages and get the property model of a certain message.
In native, components/messages/android/mock_message_dispatcher_bridge.h is available to test whether a message is enqueued and trigger some callbacks manually. You can refer to this CL as an example.
Some metrics have been pre-defined to help evaluate the effectiveness of a message.
Android.Messages.Enqueued
Records the message identifier each time a message is enqueued through MessageDispatcher. This histogram can be used for getting a count of messages broken down by message identifier.
Android.Messages.Dismissed.{MessageIdentifier}
Records the reason why this message is dismissed, such as primary action, timer, gesture and so on.
Android.Messages.TimeToAction.Dismiss.{MessageIdentifier}
Records the time interval the message was displayed on the screen before the user dismissed it with a gesture. The metric is NOT recorded when the user presses primary or secondary button or when the message is auto-dismissed based on timer.
Android.Messages.TimeToAction.{MessageIdentifier}
Records the time interval the message was displayed on the screen before the user explicitly dismissed it. The metric is recorded when the user presses the primary or secondary button, or dismisses the message with a gesture.