Actions

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 SDK comes with pre-made actions for common tasks such as setting/modifying tags, showing a landing page, scheduling or canceling action schedules, and deep linking. Actions can also be extended to enable custom application behaviors and engagement experiences.

Actions are sent with a push by supplying a JSON payload as a push extra with the key com.urbanairship.actions. The JSON payload is a map of the action names to action values. The values can be any valid JSON value.

Action Situations

Actions are triggered with additional context in the form of a Situation, which corresponds to the way the action was triggered. The different situations allow actions to determine whether they should run, or potentially perform different behaviors depending on this context.

Action.SITUATION_MANUAL_INVOCATION

Action is invoked manually.

Action.SITUATION_PUSH_RECEIVED

Action is triggered when a push is received.

Action.SITUATION_PUSH_OPENED

Action is triggered when a notification is opened.

Action.SITUATION_WEB_VIEW_INVOCATION

Action is triggered from a web view.

Action.SITUATION_FOREGROUND_NOTIFICATION_ACTION_BUTTON

Action is triggered from a foreground notification action button.

Action.SITUATION_BACKGROUND_NOTIFICATION_ACTION_BUTTON

Action is triggered from a background notification action button.

Action.SITUATION_AUTOMATION

Action is triggered 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.

Action customAction = new CustomAction();
UAirship.shared()
        .getActionRegistry()
        .registerAction(customAction, "my_action_name");

val customAction: Action = CustomAction()
UAirship.shared()
    .actionRegistry
    .registerAction(customAction, "my_action_name")

ActionRegistry.Entry entry = UAirship.shared()
                                     .getActionRegistry()
                                     .getEntry("my_action_name");

val entry = UAirship.shared()
        .actionRegistry
        .getEntry("my_action_name")

// Predicate that will reject PUSH_RECEIVED causing the action to never run during that situation.
Predicate<ActionArguments> rejectPushReceivedPredicate = new Predicate<ActionArguments>() {
    @Override
    public boolean apply(ActionArguments arguments) {
        return !(Situation.PUSH_RECEIVED.equals(arguments.getSituation()));
    }
};

entry.setPredicate(rejectPushReceivedPredicate);

val rejectPushReceivedPredicate: ActionRegistry.Predicate = object : ActionRegistry.Predicate {
    override fun apply(arguments: ActionArguments): Boolean {
        return SITUATION_PUSH_RECEIVED != arguments.situation
    }
}

entry?.predicate = rejectPushReceivedPredicate

Triggering Actions

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

The ActionRunRequest class provides a fluent API for running actions. The action run request takes in a value, situation, and metadata and constructs the ActionArguments and passes it to the action to run.

The ActionArguments value can only contain an ActionValue instance. ActionValue is a class that limits the type of values to those that can be JSON serializable and contain getter methods that automatically do type checking to parse value back into its original form. Each action is run on its own thread when triggered asynchronously. Synchronous runs will block and should never be called on the UI thread.

// Running an action directly through the ActionRunRequest
ActionRunRequest.createRequest("actionName")
                .setSituation(Situation.MANUAL_INVOCATION)
                .setValue("actionValue")
                .run();

// Running an action by registered name
ActionRunRequest.createRequest("my_action_name")
                .setValue("actionValue")
                .run();

// An optional callback when finished
ActionRunRequest.createRequest("my_action_name")
                .setValue("actionValue")
                .run(new ActionCompletionCallback() {
                    public void onFinish(ActionArguments arguments, ActionResult result) {
                        Logger.info("Action finished!  Result: " + result);
                    }
                });

// Block until the action finishes
ActionResult result = ActionRunRequest.createRequest("my_action_name")
                                      .runSync();

// Running an action directly through the ActionRunRequest
ActionRunRequest.createRequest("actionName")
        .setSituation(SITUATION_MANUAL_INVOCATION)
        .setValue("actionValue")
        .run()

// Running an action by registered name
ActionRunRequest.createRequest("my_action_name")
        .setValue("actionValue")
        .run()

// An optional callback when finished
ActionRunRequest.createRequest("my_action_name")
        .setValue("actionValue")
        .run { arguments, result -> Logger.info("Action finished!  Result: $result") }

// Block until the action finishes
val result = ActionRunRequest.createRequest("my_action_name")
        .runSync()

Available Actions

LandingPageAction

The landing page action allows showing a rich content page in an overlay. Under the default SDK settings any URLs external to Airship or YouTube will need to be allow-listed. Requires adding the urbanairship-automation module.

OpenExternalUrlAction

The open external URL action allows launching any URL. The action will construct an intent with a given URI and try to start an activity with it for viewing. Under the default SDK settings only Airship, Youtube, sms:, mailto: and tel: URLs are allowed. All others will need to be allow-listed.

DeepLinkAction

The deep link action works exactly as the Open External URL Action. It constructs an intent with a given URI and tries to launch an activity. The deep linking strategy assumes the application is set up to handle URIs. See Deep Linking for Android for more details on providing deep linking.

ShareAction

The share action constructs an intent to share the text to the application. The Android chooser activity will be started to pick the application used to share the text.

AddTagsAction

The add tags action allows adding one or more tags to the device. Note: this action is a no-op if channelTagRegistrationEnabled is set to false on PushManager .

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 documentation for more details on Custom Events.

ClipboardAction

The clipboard action copies text to the system clipboard.

MessageCenterAction

The action will try to start an activity to view either the Message Center Inbox, or a Message Center Message if a message ID is supplied as the argument’s value and the message is present in the inbox. Requires adding the urbanairship-message-center module.

WalletAction

The wallet action allows opening Google Pay deep links.

ScheduleAction

The schedule action schedules an automation action. Requires adding the urbanairship-automation module.

CancelSchedulesAction

The cancel schedules action cancels automation actions. Requires adding the urbanairship-automation module.

FetchDeviceInfoAction

The fetch device info action gets an updated snapshot of the device’s information from the JavaScript bridge.

EnableFeatureAction

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, then register the action to the registry after UAirship.takeOff .

public class CustomAction extends Action {

    @Override
    public boolean acceptsArguments(ActionArguments arguments) {
        if (!super.acceptsArguments(arguments)) {
            return false;
        }

        // Do any argument inspections. The action will stop
        // execution if this method returns false.

        return true;
    }

    @Override
    public ActionResult perform(ActionArguments arguments) {
        Logger.info("Action is performing!");

        return ActionResult.newEmptyResult();
    }
}

class CustomAction : Action() {
    override fun acceptsArguments(arguments: ActionArguments): Boolean {
        if (!super.acceptsArguments(arguments)) {
            return false
        }

        // Do any argument inspections. The action will stop
        // execution if this method returns false.

        return true

    }

    override fun perform(arguments: ActionArguments): ActionResult {
        Logger.info("Action is performing!")
        return ActionResult.newEmptyResult()
    }
}

@Override
public void onAirshipReady(UAirship airship) {
      airship.getActionRegistry()
             .registerAction(new CustomAction(), "my_custom_action");
}

override fun onAirshipReady(airship: UAirship) {
    airship.actionRegistry.registerAction(CustomAction(), "my_custom_action")
}

The action can then be triggered the same way as the built-in actions.