Actions

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 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
Airship.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 = Airship.shared.actionRegistry.registryEntry("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
let predicate: (ActionArguments) -> Bool = { args in
    return args.situation == .launchedFromPush
}

// Update the predicate
Airship.shared.actionRegistry.update(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 ActionRunner, by defining actions in a push notification, from JavaScript using a Custom HTML Template, or from an automation schedule.

// Run an action by name
ActionRunner.run("action_name", value: "action_value", situation: .manualInvocation) { result in
    print("Action finished!")
}

// Run an action directly
ActionRunner.run(action, value: "action_value", situation: manualInvocation) { result 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];

Available Actions

UALandingPageAction
The landing page action allows showing a Message Center content page in an overlay. Under the default SDK settings any URLs external to Airship or YouTube will need to be allow-listed.
OpenExternalURLAction
The open external URL action allows launching any URL. The action will attempt to open the URL using Safari. Under the default SDK settings only Airship, YouTube, sms:, mailto: and tel: URLs are allowed. All others will need to be allow-listed. This action also provides deep linking. See Deep Linking for iOS for more details on implementing deep linking.
DeepLinkAction
The deep link action works similarly to the Open External URL Action. If a deep link listener is configured, the action will attempt to call it, otherwise it will try to open the deep link as a URL using Safari, in which case the allow-list rules described above will apply. See Deep Linking for iOS for more details on implementing deep linking.
ShareAction
The share action shares text using UIActivityViewController.
AddTagsAction
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.
RemoveTagsAction
The remove tags action allows removing one or more tags from the device.
AddCustomEventAction
The custom event action creates and adds a custom event. See Custom Events for more details on Custom Events.
PasteboardAction
The pasteboard action sets the text of the system pasteboard.
UAScheduleAction
The schedule action schedules an automation action.
UACancelSchedulesAction
The cancel schedules action cancels automation actions.
FetchDeviceInfoAction
The fetch device info action gets an updated snapshot of the devices information from the JS bridge.
EnableFeatureAction
The enable feature action enables an Airship feature, such as location, background location, or user notifications.

Extended Actions

Additional actions, such as the rate-app action are avaialble in the ExtendedActions module.

Import

For CocoaPods, import using:

@import AirshipKit;
import AirshipKit

For everything else, use:

@import AirshipExtendedActions;
import AirshipExtendedActions

Custom Actions

The action framework supports any custom actions. Create an action by extending the protocol Action 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 = BlockAction { args, completionHandler in
    print("Action is performing with args: \(args)")
    completionHandler(ActionResult.empty())
}

Airship.shared.actionRegistry.register(customAction, name:"custom_action")
id<UAAction> *customAction = [[UABlockAction alloc] initWithBlock:^(UAActionArguments *args, UAActionCompletionHandler completionHandler) {
    NSLog(@"Action is performing with args: %@", args);
    completionHandler([UAActionResult emptyResult]);
}];

[UAirship.shared.actionRegistry registerAction:customAction name:@"custom_action"];
 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 completion handler when finished.