Action Automation

Action Automation installation, usage, and cancellation.

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.

Action Automation

In Airship SDK 13.0+, automation services are available as part of the Airship framework as well as a standalone framework called AirshipAutomation.

To access the automation from the Airship framework, simply import Airship where necessary.

@import Airship;
import Airship

To access automation from the AirshipMessageCenter standalone framework, you must add a separate import statement in your code, as shown below:

@import AirshipAutomation;
import AirshipAutomation

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 UAInAppAutomation allows for synchronous and asynchronous access to the automation storage. To schedule an action schedule, first create an UAActionSchedule object.

Scheduling actions example

Scheduling Actions

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

Scheduling actions example
let actions = ["add_tags_action": "my_tag"]
let schedule = UAActionSchedule(actions: actions) { (builder) in
    let valueMatcher = UAJSONValueMatcher(whereStringEquals: "name")
    let jsonMatcher = UAJSONMatcher(valueMatcher: valueMatcher, scope:[UACustomEventNameKey])
    let predicate = UAJSONPredicate(jsonMatcher: jsonMatcher)

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

    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;
}

UAInAppAutomation.shared().schedule(schedule) { (result) in
    if (result) {
        print("Scheduled: \(schedule.identifier)")
    }
}
id actions = @{@"add_tags_action": @"my_tag"};
UAActionSchedule *scheduleInfo = [UAActionSchedule scheduleWithActions:actions builderBlock:^(UAScheduleBuilder *builder) {
    UAJSONValueMatcher *valueMatcher = [UAJSONValueMatcher matcherWhereStringEquals:@"name"];
    UAJSONMatcher *jsonMatcher = [UAJSONMatcher matcherWithValueMatcher:valueMatcher scope:@[UACustomEventNameKey]];
    UAJSONPredicate *predicate = [UAJSONPredicate predicateWithJSONMatcher:jsonMatcher];

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

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

[[UAInAppAutomation shared] schedule:schedule completionHandler:^(BOOL result) {
    if (result) {
      NSLog(@"Scheduled: %@", schedule.identifier);
    }
}];

Retrieving Scheduled Actions

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

UAInAppAutomation.shared().getActionSchedule(withID: identifier) { (schedule) in
   // get schedule
}

UAInAppAutomation.shared().getActionSchedules() { (schedules) in
    // get all schedules
}

UAInAppAutomation.shared().getActionSchedules(withGroup: group) { (schedules) in
    // get all schedules of the given group.
}
[[UAInAppAutomation shared] getActionScheduleWithID:identifier completionHandler:^(UAActionSchedule *schedule) {
    // get schedule
}];

[[UAInAppAutomation shared] getActionSchedulesWithCompletionHandler:^(NSArray<UAActionSchedule *> *schedules) {
    // get all schedules
}];

[[UAInAppAutomation shared] getActionSchedulesWithGroup:^(NSArray<UAActionSchedule *> *schedules) {
   // 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
UAInAppAutomation.shared().cancelSchedule(withID: identifier)

// Cancels all schedules of the given group
UAInAppAutomation.shared().cancelActionSchedules(withGroup: group)
// Cancels a schedule with the given identifier
[[UAInAppAutomation shared] cancelScheduleWithID:@"some_scheduled_identifier"];

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