Actions

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

UASituationManualInvocation
Action was invoked manually.
UASituationLaunchedFromPush
Action was invoked from a launched push notification.
UASituationForegroundPush
Action was invoked from a received push notification in the foreground.
UASituationBackgroundPush
Action was invoked from a received push notification in the background.
UASituationWebViewInvocation
Action was invoked from JavaScript or a URL.
UASituationForegroundInteractiveButton
Action was invoked from a foreground interactive notification button.
UASituationBackgroundInteractiveButton
Action was invoked from a background interactive notification button.
UASituationAutomation
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

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"
                            value:@"actionValue"
                        situation:UASituationManualInvocation
                completionHandler:completionHandler];

// Run an action directly
[UAActionRunner runAction:action
                    value:@"actionValue"
                situation:UASituationManualInvocation
        completionHandler:completionHandler];
 Note

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.

Available Actions

UALandingPageAction
The landing page action allows showing a Message Center content page in an overlay.
UAOpenExternalURLAction
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.
UAShareAction
The share action shares text using UIActivityViewController.
UAAddTagsAction
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.
UARemoveTagsAction
The remove tags action allows removing one or more tags from the device.
UAAddCustomEventAction
The custom event action creates and adds a custom event. See Custom Events for more details on Custom Events.
UAPasteboardAction
The pasteboard action sets the text of the system pasteboard.
UADisplayInboxAction
The display inbox action displays message center messages.
UAOverlayInboxMessageAction
The overlay Message Center action displays an inbox message in a landing page controller.
UAScheduleAction
The schedule action schedules an automation action.
UACancelSchedulesAction
The cancel schedules action cancels automation actions.
UAFetchDeviceInfoAction
The fetch device info action gets an updated snapshot of the devices information from the JS bridge.
UAEnableFeatureAction
The enable feature action enables an 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)")
    handler(UAActionResult.empty())
})

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"];