External Action Plugin

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

Usage

Install the plugin:

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

Create a handler for external actions:

import { ExternalStateHandler } from '@player-ui/external-action-plugin';

const externalActionHandler: ExternalStateHandler = async (state, options) => {
  if (state.ref === 'custom') {
    return 'next';
  }
}

Add it to Player:

import { Player } from '@player-ui/player';
import { ExternalActionPlugin } from '@player-ui/external-action-plugin';

const player = new Player({
  plugins: [
    new ExternalActionPlugin(externalActionHandler)
  ]
})

This will transition any EXTERNAL state in Player’s navigation, with a ref property of custom using the next transition.

CocoaPods

Add the subspec to your Podfile

pod 'PlayerUI/ExternalActionPlugin'

Swift Usage

For an example flow with an external state such as:

{
  "id": "test-flow",
  "data": {
    "transitionValue": "Next"
  },
  "navigation": {
    "BEGIN": "FLOW_1",
    "FLOW_1": {
      "startState": "EXT_1",
      "EXT_1": {
        "state_type": "EXTERNAL",
        "ref": "test-1",
        "transitions": {
          "Next": "END_FWD",
          "Prev": "END_BCK"
        },
        "extraProperty": "extraValue"
      },
      "END_FWD": {
        "state_type": "END",
        "outcome": "FWD"
      },
      "END_BCK": {
        "state_type": "END",
        "outcome": "BCK"
      }
    }
  }
}

The plugin can be declared to handle this external state, whether that means integrating an existing platform native experience, or doing headless processing:

let plugin = ExternalActionPlugin { state, options, transition in
        guard state.ref == "test-1" else { return transition("Prev") }
        // Options contains the dataModel as well as an evaluate function for expressions
        let transitionValue = options.data.get(binding: "transitionValue") as? String
        options.expression.evaluate("{{foo}} = 'bar'")

        let extraProperty: String? = state.extraProperty // uses @dynamicMemberLookup
        // Do some processing
        transition(transitionValue ?? "Next")
}

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

The ExternalActionPlugin adds support for handling EXTERNAL navigation states in the application. The handler, which can be provided during plugin initialization, receives three parameters:

state: NavigationFlowExternalState provides access to the information defined in the EXTERNAL state node
options: ControllerState provides access to the current player controllers
transition: (String) -> Unit is provided to enable the handler to “complete” the EXTERNAL state and transition using the provided String value

Usage

In build.gradle

implementation "com.intuit.player.plugins:external-action:$PLAYER_VERSION"

In Player constructor

import com.intuit.player.plugins.externalAction.ExternalActionPlugin

val externalActionPlugin = ExternalActionPlugin { state, options, transition ->
    // access external state node
    val extraProperty = state["extraProperty"]
    // access data model
    options.data.get("{{foo.bar}}")
    // evaluate expression
    options.expression.evaluate("{{foo.bar}} = 1")
    // do other processing or show non-player experience

    // transition to the next node using "Next"
    transition("Next")
}
AndroidPlayer(externalActionPlugin)

// handler can be configured after instantiation
externalActionPlugin.onExternalAction { /** handle external action */ }

// extension method for configuring plugin with player instance
androidPlayer.onExernalAction { /** handle external action */ }

In Player content

{
  "navigation": {
    "BEGIN": "FLOW_1",
    "FLOW_1": {
      "startState": "EXT_1",
      "EXT_1": {
        "state_type": "EXTERNAL",
        "ref": "test-1",
        "transitions": {
          "Next": "END_FWD",
          "Prev": "END_BCK"
        },
        "extraProperty": "extraValue"
      },
      "END_FWD": {
        "state_type": "END",
        "outcome": "FWD"
      },
      "END_BCK": {
        "state_type": "END",
        "outcome": "BCK"
      }
    }
  }
}

API

Public API available from sources here:

ExternalActionPlugin

Help to improve this page