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

An action is an abstraction over a unary function, which takes an argument and performs a defined 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 Urban Airship library comes with pre-made actions for common tasks such as setting/modifying tags, showing a landing page, enabling deep linking, scheduling or canceling action schedules, and deep linking. Actions can also be extended to enable custom application behaviors and engagement experiences.

In iOS, Actions are sent as part of the notification payload as top level key values, where the key is the name of the action and the value is the action's argument. The argument can be any valid JSON value.

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 was invoked manually.
Action was invoked from a launched push notification.
Action was invoked from a received push notification in the foreground.
Action was invoked from a received push notification in the background.
Action was invoked from JavaScript or a URL.
Action was invoked from a foreground interactive notification button.
Action was invoked from a background interactive notification button.
Action was invoked from 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 can run, and allows specifying alternative actions for different situations.

Registering an action
UAirship.shared().actionRegistry.register(action, names: ["action_name", "action_alias"])
[[UAirship shared].actionRegistry registerAction:action names:@[@"action_name", @"action_alias"]];
Looking up an action entry
let entry = UAirship.shared().actionRegistry.registryEntry(withName: "action_name")
UAActionRegistryEntry *entry = [[UAirship shared].actionRegistry registryEntryWithName:@"action_name"];
Setting a predicate
// Predicate that only allows the action to run if it was launched from a push
func predicate(args: UAActionArguments) -> Bool {
    return args.situation == UASituation.launchedFromPush

// Update the predicate
UAirship.shared().actionRegistry.updatePredicate(predicate, forEntryWithName: "action_name")
// Predicate that only allows the action to run if it was launched from a push
UAActionPredicate predicate = ^(UAActionArguments *args) {
    return (BOOL)(args.situation == UASituationLaunchedFromPush);

// Update the predicate
[[UAirship shared].actionRegistry updatePredicate:predicate forEntryWithName:@"action_name"];

Triggering Actions


All actions are run on the main queue. If it is possible for an action to block the main queue, it should perform its work on a background queue and call the UAActionCompletionHandler when finished.

Actions can be programmatically through the UAActionRunner , by defining actions in a push notification, from JavaScript using a Custom HTML Template, or from an automation schedule.

// Run an action by name
UAActionRunner.runAction(withName: "action_name", value: "action_value", situation: UASituation.manualInvocation) { (result: UAActionResult) in
  print("Action finished!")

// Run an action directly
UAActionRunner.runAction(action, value: "action_value", situation: UASituation.manualInvocation) { (result: UAActionResult) in
  print("Action finished!")
// Optional completion handler
UAActionCompletionHandler completionHandler = ^(UAActionResult *result) {
    NSLog(@"Action finished!");

// Run an action by name
[UAActionRunner runActionWithName:@"action_name"

// Run an action directly
[UAActionRunner runAction:action

Available Actions

The landing page action allows showing a Message Center content page in an overlay.
The open external URL action allows launching any URL. The action will attempt to open the URL using Safari. This action is also provides deep linking. See Deep Linking for iOS for more details on implementing deep linking.
The share action shares text using UIActivityViewController.
The add tags action allows adding one or more tags to the device. Note: action is a no-op when channelTagRegistrationEnabled is set to NO on UAPush , which is the default.
The remove tags action allows removing one or more tags from the device.
The custom event action creates and adds a custom event. See Custom Events for more details on Custom Events.
The pasteboard action sets the text of the system pasteboard.
The display inbox action displays message center messages.
The overlay Message Center action displays an inbox message in a landing page controller.
The schedule action schedules an automation action.
The cancel schedules action cancels automation actions.
The fetch device info action gets an updated snapshot of the devices information from the JS bridge.
The enable feature action enables an Urban Airship feature, such as location, background location, or user notifications.

Custom Actions

The action framework supports any custom actions. Create an action by extending the base action class or defining an action using blocks. After takeoff, register the action. The action can be triggered the same way as built-in actions.

Custom Action
let customAction = UAAction(block: { (args: UAActionArguments, handler: UAActionCompletionHandler) -> Void in
    print("Action is performing with UAActionArguments: \(args)")

UAirship.shared().actionRegistry.register(customAction, name:"custom_action")
UAAction *customAction = [UAAction actionWithBlock: ^(UAActionArguments *args, UAActionCompletionHandler handler) {
    NSLog(@"Action is performing with UAActionArguments: %@", args);

    handler([UAActionResult emptyResult]);

[[UAirship shared].actionRegistry registerAction:customAction name:@"custom_action"];