components/messages/README.md - chromium/src - Git at Google

 # Messages UI

 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.

 [TOC]

 ## Overview

 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.


 ## Developing a new Message UI Feature

 You need to do the following things to enable your message UI, all described in
 detail below.

 1. [Declare your message UI](#Declare-your-message-ui) by adding a Message Identifier.
 2. [Build a message model](#Build-a-message-model).
 3. [Enqueue your message model](#Enqueue-your-message-model).


 ## Declare your message UI

 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](https://chromium-review.googlesource.com/c/chromium/src/+/3139695) as an example):

 1. `components/messages/android/message_enums.h` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/components/messages/android/message_enums.h#90)]
 2. MessageIdentifier in `tools/metrics/histograms/enums.xml` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/tools/metrics/histograms/enums.xml#55511)]
 3. MessageIdentifier in `tools/metrics/histograms/metadata/android/histograms.xml` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/tools/metrics/histograms/metadata/android/histograms.xml#97)]
 4. MessageIdentifier string in `components/messages/android/java/src/org/chromium/components/messages/MessagesMetrics.java` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/components/messages/android/internal/java/src/org/chromium/components/messages/MessagesMetrics.java#102)]


 ## Build a message model

 All available model properties are defined in [components/messages/android/…/MessageBannerProperties.java](https://source.chromium.org/chromium/chromium/src/+/main:components/messages/android/java/src/org/chromium/components/messages/MessageBannerProperties.java)

 Only some of them are required:

 1. TITLE: the main text of the message UI
 2. ICON / ICON_RESOURCE_ID: the primary icon of the message UI, located at the
    start side of the UI.
 3. PRIMARY_BUTTON_TEXT: the label of the primary button, located at the end of
    the message UI.

 The rest are optional, but some of those are very commonly used:

 1. DESCRIPTION: the description / subtitle of the message UI, usually used to
    help explain the purpose of the message UI.
 2. ON_PRIMARY_ACTION: the callback function triggered when the user clicks on
    the primary button. Only called once. After this function is triggered, the
    message itself will be dismissed.
 3. ON_SECONDARY_ACTION / SECONDARY_BUTTON_MENU_TEXT / SECONDARY_ICON_CONTENT_DESCRIPTION
    / SECONDARY_ICON / SECONDARY_ICON_RESOURCE_ID: these are used to set a
    secondary action / menu. If SECONDARY_BUTTON_MENU_TEXT is configured, clicking
    on the secondary button will trigger a single-menu-item popup menu.
    Clicking on the secondary icon does not guarantee that the message will be
    automatically dismissed. We recommend the feature code to manually dismiss
    the message when secondary action callback is triggered.
     1. Note: there are changes in-flight to allow multiple menu items.
        Documentation will be updated once that lands.
 4. ON_DISMISSED: the callback function triggered when the message UI is dismissed.
    Dismiss means the message has been removed from the queue and will not be displayed again.

 You can refer to
 [this CL](https://chromium-review.googlesource.com/c/chromium/src/+/3039479/17/chrome/android/java/src/org/chromium/chrome/browser/survey/ChromeSurveyController.java#239)
 as an example on the Java side and
 [this CL](https://chromium-review.googlesource.com/c/chromium/src/+/3161257/5/chrome/browser/android/oom_intervention/near_oom_reduction_message_delegate.cc#35)
 as an example on the Native side.

 Some other, less commonly used properties are:

 * ICON_TINT_COLOR: the default icon color is blue. Use this to update the icon
   color and set TINT_NONE to disable the icon tint color.
 * DESCRIPTION_MAX_LINES: set max lines of the description. The default when this
   property isn't set is to show all the description texts, which may occupy too much screen space.


 ## Enqueue your message model

 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

 MessageDispatcher is per-window object. In Java, use
 [MessageDispatcherProvider#from](https://source.chromium.org/chromium/chromium/src/+/main:components/messages/android/java/src/org/chromium/components/messages/MessageDispatcherProvider.java;l=35)
 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.


 ### Scope

 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):

 1. **Navigation**: messages of navigation will be displayed only on the web page
    for which they are enqueued. It will be hidden (not dismissed) when the user
    switches to another tab and displayed again when the user returns to the
    target tab. It will be dismissed when user navigates to another page, such as
    navigating to [https://chromium.org](https://chromium.org) from
    [https://google.com](https://google.com) or navigating to
    [https://google.com/about](https://google.com/about) from
    [https://google.com/settings](https://google.com/settings), and also
    dismissed when the tab where the page lives is closed. This should be used
    when the content and purpose of the Message is tightly related to a certain
    page. For example, password messages should be only displayed on the page
    where the user submits the password and dismissed if the user navigates to
    another page.
 2. **Window**: messages of window scope will be displayed as long as the current
    window is alive (current window is dead usually when app is closed or user
    merges windows). It can be displayed on any tab and web page. So this scope
    should be used only when the content and purpose of the message is unrelated
    to the web page. For example, Sync Error message is related to the app rather
    than the page and works as an app-level notification. Use
    #EnqueueWindowScopedMessage to enqueue a window-scoped message.
 3. **Web_Contents**: this one is rarely used and usually not recommended unless
    really necessary. The only difference between web_contents scope and navigation
    scope is that messages of web_contents scope do not dismiss when the user
    navigates to another page; i.e. it is only dismissed when its associated
    tab is closed.


 ### Priority

 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.


 ## Dismiss your message

 As explained in [Overview](#Overview), by default, the message will be dismissed
 in the following cases:

 * Timeout
 * Swiping gesture
 * Primary action button is clicked
 * The given scope is destroyed

 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.


 ## Ownership in native

 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.


 ## Test

 On the Java side,
 [components/messages/android/test/…/messages/MessagesTestHelper.java](https://source.chromium.org/chromium/chromium/src/+/main:components/messages/android/test/java/src/org/chromium/components/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](https://chromium-review.googlesource.com/c/chromium/src/+/3161257/5/chrome/browser/android/oom_intervention/near_oom_reduction_message_delegate_unittest.cc)
 as an example.


 ## Built-in Metrics

 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.
	# Messages UI

	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.

	[TOC]

	## Overview

	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.


	## Developing a new Message UI Feature

	You need to do the following things to enable your message UI, all described in
	detail below.

	1. [Declare your message UI](#Declare-your-message-ui) by adding a Message Identifier.
	2. [Build a message model](#Build-a-message-model).
	3. [Enqueue your message model](#Enqueue-your-message-model).


	## Declare your message UI

	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](https://chromium-review.googlesource.com/c/chromium/src/+/3139695) as an example):

	1. `components/messages/android/message_enums.h` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/components/messages/android/message_enums.h#90)]
	2. MessageIdentifier in `tools/metrics/histograms/enums.xml` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/tools/metrics/histograms/enums.xml#55511)]
	3. MessageIdentifier in `tools/metrics/histograms/metadata/android/histograms.xml` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/tools/metrics/histograms/metadata/android/histograms.xml#97)]
	4. MessageIdentifier string in `components/messages/android/java/src/org/chromium/components/messages/MessagesMetrics.java` [[1](https://chromium-review.googlesource.com/c/chromium/src/+/3139695/4/components/messages/android/internal/java/src/org/chromium/components/messages/MessagesMetrics.java#102)]


	## Build a message model

	All available model properties are defined in [components/messages/android/…/MessageBannerProperties.java](https://source.chromium.org/chromium/chromium/src/+/main:components/messages/android/java/src/org/chromium/components/messages/MessageBannerProperties.java)

	Only some of them are required:

	1. TITLE: the main text of the message UI
	2. ICON / ICON_RESOURCE_ID: the primary icon of the message UI, located at the
	start side of the UI.
	3. PRIMARY_BUTTON_TEXT: the label of the primary button, located at the end of
	the message UI.

	The rest are optional, but some of those are very commonly used:

	1. DESCRIPTION: the description / subtitle of the message UI, usually used to
	help explain the purpose of the message UI.
	2. ON_PRIMARY_ACTION: the callback function triggered when the user clicks on
	the primary button. Only called once. After this function is triggered, the
	message itself will be dismissed.
	3. ON_SECONDARY_ACTION / SECONDARY_BUTTON_MENU_TEXT / SECONDARY_ICON_CONTENT_DESCRIPTION
	/ SECONDARY_ICON / SECONDARY_ICON_RESOURCE_ID: these are used to set a
	secondary action / menu. If SECONDARY_BUTTON_MENU_TEXT is configured, clicking
	on the secondary button will trigger a single-menu-item popup menu.
	Clicking on the secondary icon does not guarantee that the message will be
	automatically dismissed. We recommend the feature code to manually dismiss
	the message when secondary action callback is triggered.
	1. Note: there are changes in-flight to allow multiple menu items.
	Documentation will be updated once that lands.
	4. ON_DISMISSED: the callback function triggered when the message UI is dismissed.
	Dismiss means the message has been removed from the queue and will not be displayed again.

	You can refer to
	[this CL](https://chromium-review.googlesource.com/c/chromium/src/+/3039479/17/chrome/android/java/src/org/chromium/chrome/browser/survey/ChromeSurveyController.java#239)
	as an example on the Java side and
	[this CL](https://chromium-review.googlesource.com/c/chromium/src/+/3161257/5/chrome/browser/android/oom_intervention/near_oom_reduction_message_delegate.cc#35)
	as an example on the Native side.

	Some other, less commonly used properties are:

	* ICON_TINT_COLOR: the default icon color is blue. Use this to update the icon
	color and set TINT_NONE to disable the icon tint color.
	* DESCRIPTION_MAX_LINES: set max lines of the description. The default when this
	property isn't set is to show all the description texts, which may occupy too much screen space.


	## Enqueue your message model

	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

	MessageDispatcher is per-window object. In Java, use
	[MessageDispatcherProvider#from](https://source.chromium.org/chromium/chromium/src/+/main:components/messages/android/java/src/org/chromium/components/messages/MessageDispatcherProvider.java;l=35)
	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.


	### Scope

	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):

	1. Navigation: messages of navigation will be displayed only on the web page
	for which they are enqueued. It will be hidden (not dismissed) when the user
	switches to another tab and displayed again when the user returns to the
	target tab. It will be dismissed when user navigates to another page, such as
	navigating to [https://chromium.org](https://chromium.org) from
	[https://google.com](https://google.com) or navigating to
	[https://google.com/about](https://google.com/about) from
	[https://google.com/settings](https://google.com/settings), and also
	dismissed when the tab where the page lives is closed. This should be used
	when the content and purpose of the Message is tightly related to a certain
	page. For example, password messages should be only displayed on the page
	where the user submits the password and dismissed if the user navigates to
	another page.
	2. Window: messages of window scope will be displayed as long as the current
	window is alive (current window is dead usually when app is closed or user
	merges windows). It can be displayed on any tab and web page. So this scope
	should be used only when the content and purpose of the message is unrelated
	to the web page. For example, Sync Error message is related to the app rather
	than the page and works as an app-level notification. Use
	#EnqueueWindowScopedMessage to enqueue a window-scoped message.
	3. Web_Contents: this one is rarely used and usually not recommended unless
	really necessary. The only difference between web_contents scope and navigation
	scope is that messages of web_contents scope do not dismiss when the user
	navigates to another page; i.e. it is only dismissed when its associated
	tab is closed.


	### Priority

	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.


	## Dismiss your message

	As explained in [Overview](#Overview), by default, the message will be dismissed
	in the following cases:

	* Timeout
	* Swiping gesture
	* Primary action button is clicked
	* The given scope is destroyed

	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.


	## Ownership in native

	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.


	## Test

	On the Java side,
	[components/messages/android/test/…/messages/MessagesTestHelper.java](https://source.chromium.org/chromium/chromium/src/+/main:components/messages/android/test/java/src/org/chromium/components/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](https://chromium-review.googlesource.com/c/chromium/src/+/3161257/5/chrome/browser/android/oom_intervention/near_oom_reduction_message_delegate_unittest.cc)
	as an example.


	## Built-in Metrics

	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.