AppIntent#

AppIntentManager is used to register and manage AppIntents in the Scripting app. It serves as the core mechanism for executing script logic behind controls in Widgets, Live Activities, and ControlWidgets.

All AppIntents must be defined in the app_intents.tsx file. When an intent is executed, the script runs in the "app_intents" environment (Script.env === "app_intents").

Once registered, these intents can be triggered by Button and Toggle controls within Widgets, Live Activities, or ControlWidgets, allowing users to define interactive behavior via script.

#1. Type Definitions

#AppIntent<T>

Represents a concrete intent instance with parameters and metadata.

#AppIntentFactory<T>

A factory function that creates an AppIntent instance with specified parameters.

type AppIntentFactory<T> = (params: T) => AppIntent<T>

#AppIntentPerform<T>

A function that handles intent execution logic asynchronously.

type AppIntentPerform<T> = (params: T) => Promise<void>

#AppIntentProtocol

An enumeration that defines the behavior type of the intent.

#2. AppIntentManager Class

#AppIntentManager.register<T>(options): AppIntentFactory<T>

Registers a new AppIntent by specifying its name, protocol, and perform logic. When a control (e.g., Button or Toggle) triggers the intent, the associated perform function is called.

static register<T = undefined>(options: {
  name: string;
  protocol: AppIntentProtocol;
  perform: AppIntentPerform<T>;
}): AppIntentFactory<T>

#Parameters:

#Returns:

• AppIntentFactory<T>: A factory function that creates an AppIntent instance with the specified parameters.

#Example:

// app_intents.tsx
export const ToggleDoorIntent = AppIntentManager.register({
  name: "ToggleDoorIntent",
  protocol: AppIntentProtocol.AppIntent,
  perform: async ({ id, newState }: { id: string; newState: boolean }) => {
    // Custom logic: toggle the door state
    await setDoorState(id, newState)
    // Notify UI to refresh toggle state
    ControlWidget.reloadToggles()
  }
})

In a control view file (e.g., control_widget_toggle.tsx):

ControlWidget.present(
  <ControlWidgetToggle
    intent={ToggleDoorIntent({ id: "door1", newState: !currentState })}
    label={{
      title: "Door 1",
      systemImage: currentState ? "door.garage.opened" : "door.garage.closed"
    }}
    activeValueLabel={{ title: "The door is opened" }}
    inactiveValueLabel={{ title: "The door is closed" }}
  />
)

In a widget file (widget.tsx):

<Toggle
  title="Door 1"
  value={currentState}
  intent={ToggleDoorIntent({ id: "door1", newState: !currentState })}
/>

#3. Execution Environment

All AppIntents registered via AppIntentManager are executed in the "app_intents" environment. This allows safe use of APIs suitable for background execution, such as:

• Fetching data from the network
• Controlling Live Activities
• Triggering control view refreshes

#4. Best Practices

1. Centralized Definitions: All AppIntents must be defined in app_intents.tsx for discoverability and maintainability.

2. Strong Typing: Define explicit parameter types T for both perform and control usage to benefit from type checking and autocomplete.

3. Choose the Right Protocol:

   • General operation → AppIntent
   • Audio playback → AudioPlaybackIntent
   • Audio recording → AudioRecordingIntent (requires iOS 18+, with Live Activity)
   • Live Activity control → LiveActivityIntent

4. Trigger UI Updates: If the intent modifies a UI state (e.g., toggle), call:

   • ControlWidget.reloadButtons()
   • ControlWidget.reloadToggles()
   • Widget.reloadAll() depending on where the control is hosted.