Actions for the Apple SDK

An action describes a function, which takes an optional argument and performs a predefined task, producing an optional result. Actions may restrict or vary the work they perform depending on the arguments they receive, which may include type introspection and runtime context.

The Airship SDK includes built-in actions for common tasks, and you can create custom actions to extend functionality. In iOS, actions are sent as part of the notification payload as top-level key values, where the key is the action name and the value is the action’s argument (any valid JSON value).

For a complete list of available built-in actions, see the Actions User Guide.

Action Situations

Actions are triggered with extra context in the form of a Situation. The different situations allows actions to determine if they should run or not, and possibly do different behavior depending on the situation.

Action Registry

The action registry is the central place to register actions by name. Each entry in the registry contains an action, the names that the action is registered under, a predicate that allows filtering when an action should run, and allows specifying alternative actions for different situations.

Airship.actionRegistry.registerEntry(
    names: ["action_name", "action_alias"],
) {
    return ActionEntry(action: action)
}

let entry = Airship.actionRegistry.entry(name: "action_name")

// Predicate that only allows the action to run if it was launched from a push
let predicate: @Sendable (ActionArguments) async -> Bool = { args in
    return args.situation == .launchedFromPush
}

// Update the predicate
Airship.actionRegistry.updateEntry(name: "action_name", predicate: predicate)

Triggering Actions

In addition to triggering an action from a message, they can be programmatically triggered as well.

let result = await ActionRunner.run(
  actionName: "action_name",
  arguments: ActionArguments(
    string: "some value",
    situation: .manualInvocation
  )
)

// Run an action directly
let result = await ActionRunner.run(
  action: action,
  arguments: ActionArguments(
    string: "some value",
    situation: .manualInvocation
  )
)

Custom Actions

The action framework supports any custom actions. Create an action by extending the Action protocol on iOS. iOS also allows actions to be defined using blocks. After takeoff, register the action. The action can be triggered the same way as built-in actions.

let customAction = BlockAction { args in
  print("Action is performing with args: \(args)")
  return nil
}

Airship.actionRegistry.registerEntry(names: ["custom_action"]) {
  return ActionEntry(action: customAction)
}