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: {}
      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:
        # We'd like this to be ActionName, but actions can be https:// URLs,
        # not just limited to keys in the actions map.
        # This would be a breaking change.
        type: Text
        description: >
          A URL of a page or a deeplink.
          This may have substitution variables in.          
        # This should never be defaulted.
        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:
        type: List<TriggerName>
        description: >
          A list of strings corresponding to
          targeting expressions. The message will be
          shown if all expressions `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.