External State

The External State Plugin is an easy way to handle EXTERNAL states from the navigation of a Player flow.

You provide an array of handlers, each specifying a ref to match against, an optional match object for additional properties, and a handlerFunction to run. When Player transitions to an EXTERNAL state, the plugin finds the best matching handler and calls it with the state and the player controllers.

For react, the handler should return the transition to take. For mobile, the handler is passed a callback to trigger the next transition.

Handler Matching

Handlers are matched using the Partial Match Registry. More specific handlers (those with more matching properties) take precedence over less specific ones. See the registry documentation for full details on fuzzy matching and specificity.

To register additional handlers after a plugin instance has been created, add a new ExternalStatePlugin instance to the Player.

Example flow

An EXTERNAL state in a Player flow looks like this:

{
  "navigation": {
    "BEGIN": "FLOW_1",
    "FLOW_1": {
      "startState": "EXT_1",
      "EXT_1": {
        "state_type": "EXTERNAL",
        "ref": "my-action",
        "transitions": {
          "Next": "END_FWD",
          "Prev": "END_BCK"
        }
      },
      "END_FWD": { "state_type": "END", "outcome": "FWD" },
      "END_BCK": { "state_type": "END", "outcome": "BCK" }
    }
  }
}

Specificity

You can register multiple handlers for the same ref. The most specific match wins:

new ExternalStatePlugin([
  // Matches any state with ref: 'my-action'
  { ref: "my-action", handlerFunction: () => "default" },

  // Takes precedence when type: 'special' is also present on the state
  {
    ref: "my-action",
    match: { type: "special" },
    handlerFunction: () => "special",
  },
]);

Error handling

The plugin captures an ExternalStateError (type: "externalState") via the ErrorController in two cases instead of silently stalling the flow:

• missing-handler — no registered handler matches the state’s ref.
• missing-transition-value — a handler ran but returned a falsy value (undefined or "").

metadata.ref is set to the offending state’s ref. Recover via errorTransitions or by tapping errorController.hooks.onError; see Error Handling.

Handlers that throw fail the flow directly and bypass the ErrorController — exceptions are treated as programmer errors, not recoverable content-shape issues.

Installation

Core

npm

npm i @player-ui/external-state-plugin

yarn

yarn add @player-ui/external-state-plugin

pnpm

pnpm add @player-ui/external-state-plugin

Android

implementation("com.intuit.playerui.plugins:external-state:$PLAYER_VERSION")

iOS

Swift Package Manager

Add the product to the appropriate target's dependencies in your Package.swift.

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "PlayerUIExternalStatePlugin", package: "playerui-swift-package"),
    ]
)

In your Swift file, import the sub-package. A different import is needed for each PlayerUI sub-package.

import PlayerUIExternalStatePlugin

Usage

Core

import { ExternalStatePlugin } from "@player-ui/external-state-plugin";
import { Player } from "@player-ui/player";

const player = new Player({
  plugins: [
    new ExternalStatePlugin([
      {
        ref: "my-action",
        handlerFunction: async (state, options) => {
          // options.data and options.expression are available here
          return "Next";
        },
      },
    ]),
  ],
});

Android

import com.intuit.playerui.plugins.externalState.ExternalStatePlugin

val player = AndroidPlayer(
  ExternalStatePlugin(
    ExternalStateHandler(ref = "my-action") { state, options, transition ->
      // options.data and options.expression are available here
      transition("Next")
    }
  )
)

ExternalStatePlugin API source

iOS

let plugin = ExternalStatePlugin(handlers: [
  ExternalStateHandler(ref: "my-action") { state, options, transition in
    // options.data and options.expression are available here
    // Extra state properties are accessible via @dynamicMemberLookup:
    let extraProperty: String? = state.extraProperty
    transition("Next")
  }
])

var body: some View {
  SwiftUIPlayer(
    flow: flow,
    plugins: [plugin],
    result: $resultBinding
  )
}

For SwiftUI flows that need to present native UI during an external state, see External State View Modifier.