# Actions for the Apple SDK

Airship Actions provide a convenient way to automatically perform tasks by
name in response to push notifications, Message Center App Page interactions,
and JavaScript.


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](https://www.airship.com/docs/guides/messaging/messages/actions/).

## 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.

| Description | iOS |
|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| Action was invoked manually. | [manualInvocation](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/manualinvocation)
 |
| Action was invoked from a launched push notification. | [launchedFromPush](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/launchedfrompush)
 |
| Action was invoked from a received push notification in the foreground. | [foregroundPush](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/foregroundpush)
 |
| Action was invoked from a received push notification in the background. | [backgroundPush](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/backgroundpush)
 |
| Action was invoked from JavaScript or a URL. | [webViewInvocation](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/webviewinvocation)
 |
| Action was invoked from a foreground interactive notification button. | [foregroundInteractiveButton](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/foregroundinteractivebutton)
 |
| Action was invoked from a background interactive notification button. | [backgroundInteractiveButton](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/backgroundinteractivebutton)
 |
| Action was invoked from automation. | [automation](https://urbanairship.github.io/ios-library/v20/AirshipCore/documentation/airshipcore/actionsituation/automation)
 |

## 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.


#### Swift


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



#### Objective-C


> **Note:** Actions are not supported in Objective-C.





#### Swift


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



#### Objective-C


> **Note:** Actions are not supported in Objective-C.





#### Swift


```swift
// 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)
```



#### Objective-C


> **Note:** Actions are not supported in Objective-C.




## Triggering Actions

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


#### Swift


```swift
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
  )
)
```



#### Objective-C


> **Note:** Actions are not supported in Objective-C.




## 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.


#### Swift


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

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



#### Objective-C


> **Note:** Actions are not supported in Objective-C.