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.
{
"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> := <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.
"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
// 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
When a UAActionSchedule instance is scheduled, the module will return a UASchedule instance with a unique ID generated for the schedule.
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];