Action Automation

Action 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

The API provided in UAAutomation allows for access to the automation storage.

Scheduling Actions

When a UAActionScheduleInfo instance is scheduled, the module will return a UASchedule instance with a unique ID generated for the the schedule.

Scheduling actions example

// Build the schedule info
let scheduleInfo = UAActionScheduleInfo { (builder) in
    let valueMatcher = UAJSONValueMatcher(whereStringEquals: "name")
    let jsonMatcher = UAJSONMatcher(valueMatcher: valueMatcher, key: UACustomEventNameKey)
    let predicate = UAJSONPredicate(jsonMatcher: jsonMatcher)

    let customEventTrigger = UAScheduleTrigger.customEventTrigger(with: predicate, count: 2)
    let foregroundEventTrigger = UAScheduleTrigger.foregroundTrigger(withCount: 2)

    builder.actions = ["add_tags_action": "my_tag"]
    builder.triggers = [customEventTrigger, foregroundEventTrigger]
    builder.group = "group_name";
    builder.limit = 4;
    builder.start = NSDate(timeIntervalSinceNow: 10) as Date;
    builder.end = NSDate(timeIntervalSinceNow: 1000) as Date;
}

// Schedule the schedule info
UAirship.automation().scheduleActions(scheduleInfo) { (schedule) in
    print("Unique schedule identifier: \(schedule!.identifier)");
}

// Build the schedule info
UAActionScheduleInfo *scheduleInfo = [UAActionScheduleInfo actionScheduleInfoWithBuilderBlock:^(UAActionScheduleInfoBuilder *builder) {
    UAJSONValueMatcher *valueMatcher = [UAJSONValueMatcher matcherWhereStringEquals:@"name"];
    UAJSONMatcher *jsonMatcher = [UAJSONMatcher matcherWithValueMatcher:valueMatcher key:UACustomEventNameKey];
    UAJSONPredicate *predicate = [UAJSONPredicate predicateWithJSONMatcher:jsonMatcher];

    UAScheduleTrigger *customEventTrigger = [UAScheduleTrigger customEventTriggerWithPredicate:predicate count:2];
    UAScheduleTrigger *foregroundEventTrigger = [UAScheduleTrigger foregroundTriggerWithCount:2];

    builder.actions = @{@"add_tags_action": @"my_tag"};
    builder.triggers = @[customEventTrigger, foregroundEventTrigger];
    builder.group = @"group_name";
    builder.limit = 4;
    builder.start = [NSDate dateWithTimeIntervalSinceNow:10];
    builder.end = [NSDate dateWithTimeIntervalSinceNow:1000];
}];

// Schedule the schedule info
[[UAirship automation] scheduleActions:scheduleInfo completionHandler:^(UASchedule *schedule) {
    NSLog(@"Unique schedule identifier: %@", schedule.identifier);
}];

Retrieving Scheduled Actions

The API provides methods for retrieving a single schedule, group of schedules, or all schedules.

UAirship.automation().getScheduleWithID(identifier) { (schedule) in
    // get schedule
}

UAirship.automation().getSchedules { (schedule) in
    // get all schedules
}

UAirship.automation().getSchedulesWithGroup("group_name") { (schedule) in
    // get all schedules of the given group.
}

[[UAirship automation] getScheduleWithID:identifier completionHandler:^(UASchedule *schedule) {
    // get schedule
}];

[[UAirship automation] getSchedules:^(NSArray<UASchedule *> *result) {
    // get all schedules
}];

[[UAirship automation] getSchedulesWithGroup:@"group_name" completionHandler:^(NSArray<UASchedule *> *result) {
    // get all schedules of the given 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.

// Cancels a schedule with the given identifier
UAirship.automation().cancelSchedule(withID:"some_scheduled_identifier")

// Cancels all schedules of the given group
UAirship.automation().cancelSchedules(withGroup: "some_group_name")

// Cancels all schedules
UAirship.automation().cancelAll()

// Cancels a schedule with the given identifier
[[UAirship automation] cancelScheduleWithID:@"some_scheduled_identifier"];

// Cancels all schedules of the given group
[[UAirship automation] cancelSchedulesWithGroup:@"some_group_name"];

// Cancels all schedules
[[UAirship automation] cancelAll];