Action Automation

On-device automation allows the Airship SDK to execute actions when certain conditions are met upon the creation of an analytics event. These conditions are defined as triggers and range from app foreground to screen events. Actions can be scheduled either through an action or using the APIs exposed by the SDK.

Using the Automation Actions

The "schedule_actions" action enables scheduling through the Push API as an "app defined" action, through the Airship JavaScript bridge, or directly in the SDK by manually running the action. There are several components to this schedule payload.

Schedule Payload

group
Optional, group identifier. Useful for canceling and retrieving schedules for a specific campaign.
start
Optional, start time as an ISO 8601 timestamp. The time before the schedule starts listening for events.
end
Optional, end time as ISO 8601 timestamp. Once the schedule end time is reached, it will automatically be canceled.
triggers
Required, an array of triggers. Triggers cause the actions payload to execute.
delay
Optional, a payload of time and/or app conditions that must be met before the actions are able to be executed. The delay occurs after one of the triggers hits its goals.
limit
Optional, integer defaulting to 1. Number of times to trigger the actions payload before canceling the schedule.
actions
Required, map of actions payloads. Run when one or more of the triggers meets its goal.

Trigger Payload

type
Required, the event type. Must be one of the valid types below. Each trigger type defines how the goal is incremented and the predicate argument.
goal
Required, the trigger's goal. When the trigger's goal is met, it will trigger the schedule's actions to be executed.
predicate
Optional, predicate to filter out events.

Trigger Types

custom_event_value
Custom event's value will be applied to the trigger's goal. Predicate is applied to the event.
custom_event_count
Custom events will be counted towards the trigger's goal. Predicate is applied to the event.
app_init
App init counts will be counted towards the trigger's goal. The predicate is ignored.
foreground
App foreground counts will be counted towards the trigger's goal. Predicate is ignored.
background
App background counts will be counted towards the trigger's goal. The predicate is ignored.
region_enter
Region enter events will be counted towards the trigger's goal. Predicate is applied to the event.
region_exit
Region exit events will be counted towards the trigger's goal. Predicate is applied to the event.
screen
Screen tracking. Predicate is applied against the screen's name.

The following is an example schedule payload that will display a landing page after a user has either visited a given page ten times or, as reported through a custom event, purchased items beyond a threshold of $30.

Example schedule payload
{
   "schedule_actions" :{
      "actions":{
         "landing_page_action":"https://www.airship.com"
      },
      "limit": 1,
      "start": "2015-04-01T12:00:00",
      "end": "2017-05-01T12:00:00",
      "group": "campaign 1",
      "triggers": [
         {
            "type": "screen",
            "goal": 10,
            "predicate": {
               "value": {
                  "equals": "purchase_page"
               }
            }
         },
         {
            "type": "custom_event_count",
            "goal": 1.0,
            "predicate": {
               "and" : [
               {
                  "key": "event_name",
                  "value": {
                     "equals": "purchase"
                  }
               },
               {
                  "key": "price",
                  "scope": ["properties"],
                  "value": {
                     "at_least": "30.0"
                  }
               }]
            }
         }
      ]
   }
}

Trigger Predicates

The predicate is the core logic within the trigger, presenting a set of structured conditions that are applied to the trigger event. It follows the same patterns as in Custom Event Selectors and may be a value matcher or logical expression.

Predicate syntax
<predicate>        := <json_matcher> | <not> | <and> | <or>
<not>              := { "not": { <predicate> } }
<and>              := { "and": [<predicate>, <predicate>, …] }
<or>               := { "or": [<predicate>, <predicate>, …] }
<json_matcher>     := { <selector>, "value": { <value_matcher> }} | { "value": {<value_matcher>}}
<selector>         := <scope>, "key": string | "key": string | <scope>
<scope>            := "scope": string | "scope": [string, string, …]
<value_matcher>    := <numeric_matcher> | <string_matcher> | <presence_matcher>
<numeric_matcher>  := "equals": number | "at_least": number | "at_most": number | "at_least": number, "at_most": number
<string_matcher>   := "equals": string
<presence_matcher> := "is_present": boolean

Delay Payload

seconds
Optional, minimum time in seconds that is needed to pass before running the actions.
region_id
Optional, specifies the ID of a region that the device must currently be in before the schedule's actions are able to be executed.
screen
Optional, specifies the name of an app screen that the user must currently be viewing before the schedule's actions are able to be executed.
app_state
Optional, specifies the app state that is required before the schedule's actions are able to execute. Either "foreground" or "background".
cancellation_triggers
Optional, triggers that will cancel the pending execution of the actions.
Example delay payload
"delay": {

  // Minimum time in seconds that is needed to pass before running the actions
  "seconds": 10.5,

  // Specifies the ID of a region that the device must currently be in before
  // the schedule's actions are able to be executed.
  "region_id": "region id",

  // Specifies the name of an app screen that the user must currently be
  // viewing before the schedule's actions are able to be executed.
  "screen": "screen name",

  // Specifies the app state that is required before the schedule's actions
  // are able to execute. Either foreground or background.
  "app_state": "foreground",

  // These triggers will cancel the pending execution of the actions
  "cancellation_triggers": [ // triggers ],
}

Cancelling Actions

Just like scheduling actions, canceling scheduled actions can be done with the "cancel_scheduled_actions" action.

all
Optional. Value for canceling all schedules.
group
Optional. Either a single group or an array of groups
ids
Optional. Either a single ID or an array of IDs
Example cancel action payload
// Cancel all scheduled actions
"cancel_scheduled_actions": "all"

// Cancel specific groups and/or ids
"cancel_scheduled_actions": {
   "ids": ["id 1", "id 2"],
   "groups": ["campaign 1", "campaign 2"]
}

Using the Automation API

 Note

It should be noted that the automation module cannot be accessed off of the main process. If any method is called, the method will no-op and execute the callback, if provided.

The API provided in Automation allows for synchronous and asynchronous access to the automation storage. To schedule an action schedule, first create an ActionScheduleInfo object.

When an ActionScheduleInfo instance is scheduled, the module will return an ActionSchedule instance with a unique ID generated for the schedule. When scheduling asynchronously, a callback may be provided to handle this response. If present, the callback will be posted to the calling thread's looper. The main thread's looper will otherwise be used.

Scheduling actions example
Trigger customEventTrigger = Triggers.newCustomEventTriggerBuilder()
                                     .setCountGoal(2)
                                     .setEventName("name")
                                     .build();

Trigger foregroundEventTrigger = Triggers.newForegroundTriggerBuilder()
                                         .setGoal(3)
                                         .build();

ActionScheduleInfo actionSchedule = ActionScheduleInfo.newBuilder()
                                                      .addTrigger(customEventTrigger)
                                                      .addTrigger(foregroundEventTrigger)
                                                      .addAction("sample_action", JsonValue.wrap("sample_action_value"))
                                                      .setGroup("group_name")
                                                      .setLimit(4)
                                                      .setStart(System.currentTimeMillis())
                                                      .setEnd(System.currentTimeMillis() + TimeUnit.MILLISECONDS.convert(1, TimeUnit.DAYS))
                                                      .build();

// Schedule the schedule info
UAirship.shared().getAutomation().schedule(actionSchedule);

Retrieving Scheduled Actions

The API provides methods for retrieving a single schedule, group of schedules, or all schedules. If retrieving asynchronously, a callback may be provided.

Retrieving a specific schedule
PendingResult<ActionSchedule> pendingResult = UAirship.shared().getAutomation().getSchedule("id");
Retrieving schedules from a group ID
PendingResult<ActionSchedule> pendingResult = UAirship.shared().getAutomation().getSchedules("group");

Cancelling Scheduled Actions

Lastly, a series of methods are provided for canceling a single schedule, a group or list of schedules, or all schedules.

UAirship.shared().getAutomation().cancel("id");
UAirship.shared().getAutomation().cancelGroup("group");