Defining and Sending Push Notifications

The Airship Ruby Library strives to match the standard Urban Airship JSON format for specifying push notifications. When creating a push notification, you:

  1. Select the audience
  2. Define the notification payload
  3. Specify device types.
  4. 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.all
push.send_push

Audience Selectors

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

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',
        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

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

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

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'])

or with the all shortcut.

push.device_types = UA.all

Delivery

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

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

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

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

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

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

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