android-components/components/service/nimbus/messaging.fml.yaml

---
about:
  description: Nimbus Feature Manifest for Android
  kotlin:
    package: mozilla.components.service.nimbus
    class: .messaging.FxNimbusMessaging
channels:
  - release
  - debug
features:
  nimbus-system:
    description: |
      Configuration of the Nimbus System in Android.
    variables:
      refresh-interval-foreground:
        description: |
          The minimum interval in minutes between fetching experiment 
          recipes in the foreground.
        type: Int
        default: 60 # 1 hour

  messaging:
    description: |
      The in-app messaging system.

    allow-coenrollment: true

    variables:
      messages:
        description: A growable collection of messages
        type: Map<MessageKey, MessageData>
        string-alias: MessageKey
        default: {}

      triggers:
        description: >
          A collection of out the box trigger
          expressions. Each entry maps to a
          valid JEXL expression.
        type: Map<TriggerName, String>
        string-alias: TriggerName
        default: {}
      styles:
        description: >
          A map of styles to configure message
          appearance.
        type: Map<StyleName, StyleData>
        string-alias: StyleName
        default: {}

      $$surfaces:
        description: |
          A list available surfaces for this app.

          This should not be written to by experiments, and should be hidden to users.
        type: List<SurfaceName>
        string-alias: SurfaceName
        default: []

      actions:
        type: Map<ActionName, String>
        description: A growable map of action URLs.
        string-alias: ActionName
        default:
          OPEN_URL: ://open

      on-control:
        type: ControlMessageBehavior
        description: What should be displayed when a control message is selected.
        default: show-next-message
      notification-config:
        description: Configuration of the notification worker for all notification messages.
        type: NotificationConfig
        default: {}
      message-under-experiment:
        description: Deprecated in favor of `MessageData#experiment`. This will be removed in future releases.
        type: Option<MessageKey>
        default: null
      $$experiment:
        description: The only acceptable value for `MessageData#experiment`. This should not be set by experiment.
        type: ExperimentSlug
        string-alias: ExperimentSlug
        default: "{experiment}"
    defaults:

objects:
  MessageData:
    description: >
      An object to describe a message. It uses human
      readable strings to describe the triggers, action and
      style of the message as well as the text of the message
      and call to action.
    fields:
      action:
        type: ActionName
        description: >
          A URL of a page or a deeplink.
          This may have substitution variables in.
        # This should never be defaulted.
        default: OPEN_URL
      action-params:
        description: >
          A string map containing query parameters that will be appended to the action URL.
          This is useful for opening URLs in tabs, or specifying that the tab should be private.
          The values may have substitutions, e.g. "url": "https://example.com/id={uuid}",
          "private": "true".

          The params and their values are all determined downstream of the messaging component, by
          the embedding app's deeplink processing machinery.
        type: Map<String, String>
        default: {}
      title:
        type: Option<Text>
        description: "The title text displayed to the user"
        default: null
      text:
        type: Text
        description: "The message text displayed to the user"
        # This should never be defaulted.
        default: ""
      is-control:
        type: Boolean
        description: "Indicates if this message is the control message, if true shouldn't be displayed"
        default: false
      experiment:
        type: Option<ExperimentSlug>
        description: The slug of the experiment that this message came from.
        default: null
      button-label:
        type: Option<Text>
        description: >
          The text on the button. If no text
          is present, the whole message is clickable.
        default: null
      style:
        type: StyleName
        description: >
          The style as described in a
          `StyleData` from the styles table.
        default: DEFAULT
      surface:
        description:
          The surface identifier for this message.
        type: SurfaceName
        default: homescreen
      trigger-if-all:
        type: List<TriggerName>
        description: >
          A list of strings corresponding to
          targeting expressions. The message will be
          shown if all expressions are `true`.
        default: []
      exclude-if-any:
        type: List<TriggerName>
        description: >
          A list of strings corresponding to
          targeting expressions. The message will not be
          shown if any of the expressions are `true`.
        default: [ ]
  StyleData:
    description: >
      A group of properties (predominantly visual) to
      describe the style of the message.
    fields:
      priority:
        type: Int
        description: >
          The importance of this message.
          0 is not very important, 100 is very important.
        default: 50
      max-display-count:
        type: Int
        description: >
          How many sessions will this message be shown to the user
          before it is expired.
        default: 5
  NotificationConfig:
    description: Attributes controlling the global configuration of notification messages.
    fields:
      refresh-interval:
        type: Int
        description: >
          How often, in minutes, the notification message worker will wake up and check for new
          messages.
        default: 240 # 4 hours

enums:
  ControlMessageBehavior:
    description: An enum to influence what should be displayed when a control message is selected.
    variants:
      show-next-message:
        description: The next eligible message should be shown.
      show-none:
        description: The surface should show no message.