# ASRouter New Tab Multistage Message

An inline multistage message surface for displaying multi-screen flows on the Firefox New Tab page.

Like `asrouter-newtab-message`, this component is packaged to take advantage of newtab train-hopping. The newtab extension knows to package this component at build-time both to the built-in instance of newtab and the train-hoppable XPI. **It is the responsibility of the owners of this component to maintain newtab train-hop compatibility. At this time, the owners of this component are the OMC team.**

## Overview

The ASRouter New Tab Multistage Message embeds the full `MultiStageAboutWelcome` React component inline on about:newtab, inside a shadow root managed by `ExternalComponentWrapper`. This allows the same multi-screen onboarding flows used in about:welcome and Spotlight to be surfaced directly on the New Tab page without a modal or overlay.

A dismiss button is rendered above the multistage content. Clicking it blocks the message permanently.

## Integration

The component is loaded dynamically through the newtab page's `ExternalComponentWrapper` using the `react-bundle` mount strategy. It is wrapped by the `MessageWrapper` component, which provides impression tracking and message lifecycle management.

The mount function exposed by the bundle is `window.mountMultistageMessage`. It receives props injected by `ExternalComponentWrapper` (which in turn receives them from `MessageWrapper` via `React.cloneElement`), sets up the AW handler bridge, renders the React tree, and returns a cleanup function.

### AW Handler Bridge

`MultiStageAboutWelcome` communicates with its host environment through a set of `window.AW*` globals. `mountMultistageMessage` installs a bridge that maps these to the newtab message lifecycle:

| Handler                          | Behaviour in this context                                                                                             |
|----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| `AWEvaluateScreenTargeting`      | Forwarded to ASRouter via `window.ASRouterMessage`                                                                    |
| `AWGetFeatureConfig`             | Returns the message `content` object                                                                                  |
| `AWFinish`                       | Calls `handleDismiss` to close the message                                                                            |
| `AWSendToParent`                 | Forwarded to ASRouter as a `USER_ACTION`                                                                              |
| `AWAddScreenImpression`          | Forwarded to ASRouter via `window.ASRouterMessage` to record a per-screen impression for frequency capping            |
| `AWSendEventTelemetry`           | Routes non-impression events to `handleClick`; IMPRESSION events are suppressed because `MessageWrapper` handles them |
| `AWGetSelectedTheme`             | Returns a resolved promise (themes not applicable in this context)                                                    |
| `AWGetInstalledAddons`           | Returns a resolved promise (not applicable in this context)                                                           |

All handlers are deleted from `window` when the component is unmounted.

### Message Configuration

Messages use the `newtab_message` template with `messageType: "ASRouterMultistageMessage"`:

```javascript
{
  id: "MY_NEWTAB_MULTISTAGE_MESSAGE",
  template: "newtab_message",
  content: {
    messageType: "ASRouterMultistageMessage",
    id: "MY_NEWTAB_MULTISTAGE_MESSAGE",
    transitions: false,
    backdrop: "transparent",
    screens: [
      {
        id: "SCREEN_1",
        content: {
          position: "center",
          title: { raw: "Title" },
          primary_button: {
            label: { raw: "Primary" },
            action: { navigate: true },
          },
        },
      },
    ],
  },
  frequency: { lifetime: 3 },
  trigger: { id: "newtabMessageCheck" },
}
```

The `screens` array follows the standard aboutwelcome multistage screen schema. See the [about:welcome documentation](./about-welcome.md) for the full list of supported screen properties.

## Handler Functions

The following functions are injected by `MessageWrapper` and provide message lifecycle management:

### `handleClose` (Function)
Closes the message and removes it from the DOM without recording any telemetry. The message may appear again in future sessions.

### `handleDismiss` (Function)
Dismisses the message, records a DISMISS telemetry event, and removes it from the DOM. Internally calls `handleClose` after recording telemetry.

### `handleBlock` (Function)
Permanently blocks the message by adding its ID to ASRouter's block list. Blocked messages are never shown again across browser restarts. The dismiss button calls both `handleBlock` and `handleDismiss`.

### `handleClick` (Function)
Records a CLICK telemetry event for user interaction with the message.

**Parameters:**
- `elementId` (string, optional): An identifier for the clicked element, used for telemetry tracking.

## Telemetry

- **Impression**: fired once by `MessageWrapper`'s intersection observer when the component enters the viewport.
- **Screen impression**: recorded via `AWAddScreenImpression` when each screen becomes active, forwarded to `ASRouter.addScreenImpression` for per-screen frequency capping.
- **Click**: fired via `AWSendEventTelemetry` for user interactions (e.g. button clicks). IMPRESSION events from `AWSendEventTelemetry` are suppressed because `MessageWrapper` handles the overall message-level impression.
- **Dismiss/Block**: fired by `handleDismiss` / `handleBlock` when the user clicks the dismiss button.

## Strings

Since this component supports train-hopping, its strings must live within `newtab.ftl`, be statically provided through the `messageData` object (e.g. `{ raw: "..." }` values in screen content), or be included in the set in `l10nURLs` for the `ASROUTER_MULTISTAGE_MESSAGE` external component definition. Usage of new strings in `newtab.ftl` must be coordinated with the New Tab team to ensure translations are available in the target regions.

The dismiss button string key is `newtab-activation-window-message-dismiss-button`, defined in `newtab.ftl`.

## Testing

See `browser/components/asrouter/tests/browser/browser_asrouter_newtab_multistage_messages.js` for browser tests that exercise the component. This test file has the `newtab` tag and is included in train-hop compatibility CI jobs.

## See Also

- [ASRouter New Tab Message](./asrouter-newtab-message.md)
- [about:welcome Documentation](./about-welcome.md)
- [New Tab External Components](../../../extensions/newtab/docs/v2-system-addon/external_components_guide.md)
- [New Tab Train-hop Compatibility](../../../extensions/newtab/docs/v2-system-addon/train_hopping.md)
- [ASRouter Documentation](../../asrouter/docs/index.rst)