Defining and Sending Push Notifications\uf0c1
The Airship Ruby Library strives to match the standard Urban Airship JSON format for specifying push notifications. When creating a push notification, you:
- Select the audience
- Define the notification payload
- Specify device types.
- Deliver the notification.
This example performs a broadcast with the same alert to all recipients and device types:
require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key:'application_key', secret:'master_secret')
push = airship.create_push
push.audience = UA.all
push.notification = UA.notification(alert: 'Hello')
push.device_types = UA.device_types(['ios','android'])
push.send_push
Audience Selectors\uf0c1
An audience should specify one or more devices. An audience can be a
device, such as a channel, device_token or apid; a tag,
alias, or segment; a location; or a combination. Audience selectors are
combined with and, or, and not.
Select all to do a broadcast.
push.audience = UA.all
Select a single iOS Channel:
push.audience = UA.ios_channel(uuid)
Select a single Android Channel:
push.audience = UA.android_channel(uuid)
Select a single Amazon Channel:
push.audience = UA.amazon_channel(uuid)
Select a single Web Channel:
push.audience = UA.channel(uuid)
Select a single Open Channel:
push.audience = UA.open_channel(uuid)
Select a single iOS device token:
push.audience = UA.device_token(token)
Select a single Android APID:
push.audience = UA.apid(uuid)
Select a single Windows APID:
push.audience = UA.wns(uuid)
Select a single tag:
push.audience = UA.tag(tag)
Select a single tag with a specified tag group (Note: defaults to device tag group when one is not provided):
push.audience = UA.tag(tag, group:'tag-group')
Select a single alias:
push.audience = UA.alias(alias)
Select a single segment:
push.audience = UA.segment(segment)
Select a single named user:
push.audience = UA.named_user(named_user)
Select devices that match at least one of the given selectors:
push.audience = UA.or(UA.tag('sports'), UA.tag('business'))
Select devices that match all of the given selectors:
push.audience = UA.and(UA.tag('sports'), UA.tag('business'))
Select devices that do not match the given selectors:
push.audience = UA.not(UA.and(UA.tag('sports'), UA.tag('business')))
Select a location expression. Location selectors are made up of either an id or an alias and a date period specifier. Use a date specification function to generate the time period specifier. Location aliases can be found here: http://docs.airship.com/reference/location_boundary_catalog.html
ID location example:
push.audience = UA.location(
id: 'location_id',
date: UA.recent_date(days: 4)
)
Alias location example:
push.audience = UA.location(
us_zip: 12345,
date: UA.recent_date(days: 4)
)
Select a recent date range for a location selector. Valid selectors are: hours ,days, weeks, months, years
recent_date(months: 6)
recent_date(weeks: 3)
Select an absolute date range for a location selector. Parameters are resolution, start, and the_end. Resolutions is one of :hours, :days, :weeks, :months, or :years. Start and the_end are UTC times in ISO 8601 format.
absolute_date(
resolution: months,
start: '2013-01', the_end: '2013-06'
)
absolute_date(
resolution: :hours,
start: '2012-01-01 11:00',
the_end: '2012-01-01 12:00')
)
Notification Payload\uf0c1
The notification payload determines what message and data is sent to a device. At its simplest, it consists of a single string-valued attribute, “alert”, which sends a push notification consisting of a single piece of text:
push.notification = UA.notification(alert: "Hello, world!")
You can override the notification payload with one of the following platform keys:
ios, amazon, android, wns
In the examples below, we override the general 'Hello World!' alert with
platform-specific alerts, and we set a number of other platform-specific options.
Example iOS Override
push.notification = UA.notification(
alert: 'Hello World!',
ios: UA.ios(
alert: 'Hello iOS!',
badge: 123,
sound: 'sound file',
extra: { 'key' => 'value', 'key2' => 'value2' },
expiry: '2019-01-01 12:45:00',
category: 'category_name',
thread_id: 'thread_test',
interactive: UA.interactive(
type: 'ua_share',
button_actions: {
share: { share: 'Sharing is caring!' }
}
),
priority: 5,
content_available: true
)
)
Example Amazon Override
push.notification = UA.notification(
alert: 'Hello World!',
amazon: UA.amazon(
alert: 'Hello Amazon!',
consolidation_key: 'key',
expires_after: '2019-01-01 12:45:00',
extra: { 'key' => 'value', 'key2' => 'value2' },
title: 'title',
summary: 'summary',
interactive: UA.interactive(
type: 'ua_share',
button_actions: {
share: { share: 'Sharing is caring!' }
}
)
)
)
Example Android Override
push.notification = UA.notification(
alert: 'Hello World!',
android: UA.android(
alert: 'Hello Android!',
collapse_key: 'key',
time_to_live: 123,
extra: { 'key' => 'value', 'key2' => 'value2' },
delay_while_idle: false,
interactive: UA.interactive(
type: 'ua_share',
button_actions: {
share: { share: 'Sharing is caring!' }
}
)
)
)
Example Web Override
push.notification = UA.notification(
alert: 'Hello World!',
web: UA.web(
alert: 'Hello Web!',
title: 'My Title',
extra: { 'key' => 'value', 'key2' => 'value2' },
require_interaction: true,
icon: { 'url' => 'https://www.airship.com'}
)
)
Example Email Override
push.notification = UA.notification(
alert: 'Hello World!',
email: UA.email(
subject: 'Hello Inbox!',
html_body: '<h2>Richtext body goes here</h2><p>Wow!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.airship.com/email/success.html\">Unsubscribe</a></p>',
plaintext_body: 'Plaintext version goes here [[ua-unsubscribe href=\"http://unsubscribe.airship.com/email/success.html\"]]',
message_type: 'commercial',
sender_name: 'Airship',
sender_address: 'team@airship.com',
reply_to: 'no-reply@airship.com'
)
)
Note
Email override MUST be used for sending emails.
Example SMS Override
push.notification = UA.notification(
alert: 'Hello World!',
sms: UA.sms(
alert: 'Hello SMS!',
expiry: '2018-04-01T12:00:00'
)
)
Note
SMS override MUST be used for sending SMS messages.
Example Open Platform Override
push.notification = UA.notification(
alert: 'Hello World!',
open_platforms: {
'open::toaster': UA.open_platform(
alert: 'Hello Toaster',
title: 'My Title',
summary: 'My Summary',
extra: { 'key' => 'value', 'key2' => 'value2' },
media_attachment: 'https://media.giphy.com/media/JYsWwF82EGnpC/giphy.gif',
interactive: UA.interactive(
type: 'ua_share',
button_actions: {
share: { share: 'Sharing is caring!' }
}
)
),
'open::refrigerator': UA.open_platform(
alert: 'Hello Fridge'
)
}
)
Example WNS Override
push.notification = UA.notification(
alert: 'Hello World!',
wns: UA.wns_payload(
alert: 'Hello WNS!',
tile: nil,
toast: nil,
badge: nil
)
)
Note
The input for wns_payload must include exactly one of alert, toast, tile, or badge.
Actions\uf0c1
Airship Actions provides a convenient way to automatically perform tasks by name in response to push notifications, Rich App Page interactions and JavaScript. More information at http://docs.airship.com/api/ua.html#actions, example:
push.notification = UA.notification(
alert: 'Hello world',
actions: UA.actions(
add_tag: 'new_tag',
remove_old: 'old_tag',
share: 'Check out Airship!',
open_: {
type: 'url',
content: 'http://www.example.com'
},
app_defined: {
some_app_defined_action: 'some_values'
},
))
Interactive Notifications\uf0c1
The interactive notification payload determines the ways you can interact with a notification. It contains two attributes: “type” (mandatory) and “button_actions” (optional). More information at http://docs.airship.com/api/ua.html#interactive-notifications Example:
push.notification = UA.notification(
alert: "Hello, world!",
interactive: UA.interactive(
type: "ua_share",
button_actions: {
share: {share: "Sharing is caring!"}
}
)
)
Button actions can also be mapped to actions objects as shown below:
shared = ua.actions(share: "Sharing is caring!")
push.notification = ua.notification(
alert: "Hello, world!",
interactive: ua.interactive(
type: "ua_share",
button_actions: {
"share" : shared
}
)
)
Device Types\uf0c1
In addition to specifying the audience, you must specify the device types you wish to target with a list of strings:
push.device_types = UA.device_types(['ios', 'android', 'web', 'open::example'])
Delivery\uf0c1
Once you have set the audience, notification, and device_types
attributes, the notification is ready for delivery.
push.send_push
If the delivery is unsuccessful, an AirshipFailure exception
will be raised.
Scheduled Delivery\uf0c1
Scheduled notifications build upon the Push object, and have two other components: the scheduled time(s) and an optional name.
This example schedules the above notification for delivery in one minute.
schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "optional name for later reference"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)
If the schedule is unsuccessful, an AirshipFailure
exception will be raised.
Scheduled Delivery in Device Local Time\uf0c1
Scheduled notifications build upon the Push object, and have two other components: the scheduled time(s) and an optional name.
This example schedules the above notification for delivery in device local time.
schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "optional name for later reference"
schedule.schedule = UA.local_scheduled_time(Time.now + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)
If the schedule is unsuccessful, an AirshipFailure exception
will be raised.
Scheduled Delivery for Optimal Send Time\uf0c1
Scheduled notifications build upon the Push object, and have two other components: the scheduled time(s) and an optional name.
This example schedules the above notification delivery for optimal send time.
schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "optional name for later reference"
schedule.schedule = UA.optimal_scheduled_time('2020-02-20')
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)
If the schedule is unsuccessful, an AirshipFailure exception
will be raised.
Note
Make sure the time for UA.optimal_scheduled_time is a date versus a timestamp.
Updating or Canceling a Schedule\uf0c1
If you have the schedule_url returned from creating a scheduled
notification, you can update or cancel it before it’s sent.
schedule = UA::ScheduledPush.from_url(client: airship, url: 'http://www.example.com')
# change scheduled time to tomorrow
schedule.schedule = UA.scheduled_time(Time.now.utc + (60 * 60 * 24))
schedule.update
# Cancel
schedule.cancel
Listing a Particular Schedule\uf0c1
If you have the schedule id, you can use it to list the details of a particular schedule.
airship = UA::Client.new(key: '123', secret: 'abc')
scheduled_push = UA::ScheduledPush.new(airship)
schedule_details = scheduled_push.list(schedule_id: 'id')
puts(schedule_details)
Note
The schedule_id can be obtained from the url of the schedule.
Listing all Schedules\uf0c1
You can list all schedules with the ScheduledPushList class:
airship = UA::Client.new(key: '123', secret: 'abc')
scheduled_push_list = UA::ScheduledPushList.new(client: airship)
scheduled_push_list.each do |schedule|
puts(schedule)
end