Actions
Airship Actions provide a convenient way to automatically perform tasks by name in response to push notifications, Message Center 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 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:
andtel:
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.
Actions that are long-lived should request a wake lock before performing.
This is especially important for actions that are performing in Situation.PUSH_RECEIVED
,
when a push is delivered when the device is not active.
Categories