Interactivity powered by state machines

Interactivity is currently in its early stages of development and not production ready. Please be aware that this API will change. If your state machine is not working as expected please create an issue on Github.

Creation

Learn how to create dotLotties with state machines here.

Usage

The DotLottieAnimation instance exposes the following state machine methods:

Method	Description
`stateMachineLoad(id: String)`	Loads a state machine by ID.
`stateMachineLoadData(_ data: String)`	Loads state machine data.
`stateMachineStart(openUrlPolicy:)`	Starts the state machine with URL policy.
`stateMachineStop()`	Stops the state machine.
`stateMachinePostEvent(_ event: Event, force: Bool?)`	Posts an event to the state machine.
`stateMachineSubscribe(_ observer: StateMachineObserver)`	Subscribe to state machine events.
`stateMachineUnSubscribe(observer: StateMachineObserver)`	Unsubscribe from state machine events.
`stateMachineSetNumericInput(key: String, value: Float)`	Set numeric input for state machine.
`stateMachineSetStringInput(key: String, value: String)`	Set string input for state machine.
`stateMachineSetBooleanInput(key: String, value: Bool)`	Set boolean input for state machine.
`stateMachineCurrentState()`	Returns the current state machine state.

State Machine Observer Events

The StateMachineObserver protocol provides the following callbacks:

Event	Description
`onStart()`	Called when state machine starts
`onStop()`	Called when state machine stops
`onTransition(previousState: String, newState: String)`	Called when transitioning between states
`onStateEntered(enteringState: String)`	Called when entering a new state
`onStateExit(leavingState: String)`	Called when exiting a state
`onError(message: String)`	Called when an error occurs in the state machine
`onCustomEvent(message: String)`	Called when a custom event is fired
`onInputFired(inputName: String)`	Called when an input is fired
`onBooleanInputValueChange(inputName, oldValue, newValue)`	Called when a boolean input value changes
`onNumericInputValueChange(inputName, oldValue, newValue)`	Called when a numeric input value changes
`onStringInputValueChange(inputName, oldValue, newValue)`	Called when a string input value changes

OpenUrlPolicy

Security policy for state machine URL opening:

let urlPolicy = OpenUrlPolicy(
    requireUserInteraction: true,  // Require user interaction before opening URLs
    whitelist: ["https://trusted-domain.com"]  // Allowed domains
)

Example Usage

// Load and start a state machine
animation.stateMachineLoad(id: "myStateMachine")
animation.stateMachineStart(openUrlPolicy: urlPolicy)

// Set inputs
animation.stateMachineSetBooleanInput(key: "isEnabled", value: true)
animation.stateMachineSetNumericInput(key: "score", value: 100.0)
animation.stateMachineSetStringInput(key: "username", value: "player1")

// Post events
let event = Event(name: "click", data: nil)
animation.stateMachinePostEvent(event, force: false)

// Subscribe to state machine events
class MyStateMachineObserver: StateMachineObserver {
    func onTransition(previousState: String, newState: String) {
        print("State changed from \(previousState) to \(newState)")
    }

    func onCustomEvent(message: String) {
        print("Custom event: \(message)")
    }

    // Implement other required methods...
}

let observer = MyStateMachineObserver()
animation.stateMachineSubscribe(observer)