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: #. 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: .. code-block:: ruby 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. .. code-block:: ruby push.audience = UA.all Select a single iOS Channel: .. code-block:: ruby push.audience = UA.ios_channel(uuid) Select a single Android Channel: .. code-block:: ruby push.audience = UA.android_channel(uuid) Select a single Amazon Channel: .. code-block:: ruby push.audience = UA.amazon_channel(uuid) Select a single Web Channel: .. code-block:: ruby push.audience = UA.channel(uuid) Select a single Open Channel: .. code-block:: ruby push.audience = UA.open_channel(uuid) Select a single iOS device token: .. code-block:: ruby push.audience = UA.device_token(token) Select a single Android APID: .. code-block:: ruby push.audience = UA.apid(uuid) Select a single Windows APID: .. code-block:: ruby push.audience = UA.wns(uuid) Select a single tag: .. code-block:: ruby 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): .. code-block:: ruby push.audience = UA.tag(tag, group:'tag-group') Select a single alias: .. code-block:: ruby push.audience = UA.alias(alias) Select a single segment: .. code-block:: ruby push.audience = UA.segment(segment) Select a single named user: .. code-block:: ruby push.audience = UA.named_user(named_user) Select devices that match at least one of the given selectors: .. code-block:: ruby push.audience = UA.or(UA.tag('sports'), UA.tag('business')) Select devices that match all of the given selectors: .. code-block:: ruby push.audience = UA.and(UA.tag('sports'), UA.tag('business')) Select devices that do not match the given selectors: .. code-block:: ruby 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: .. code-block:: ruby push.audience = UA.location( id: 'location_id', date: UA.recent_date(days: 4) ) Alias location example: .. code-block:: ruby 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 .. code-block:: ruby 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. .. code-block:: ruby 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: .. code-block:: ruby 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** .. code-block:: ruby 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** .. code-block:: ruby 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** .. code-block:: ruby 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** .. code-block:: ruby 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** .. code-block:: ruby push.notification = UA.notification( alert: 'Hello World!', email: UA.email( subject: 'Hello Inbox!', html_body: '

Richtext body goes here

Wow!

Unsubscribe

', 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** .. code-block:: ruby 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** .. code-block:: ruby 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** .. code-block:: ruby 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: .. code-block:: ruby 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: .. code-block:: ruby 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: .. code-block:: ruby 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: .. code-block:: ruby push.device_types = UA.device_types(['ios', 'android', 'web', 'open::example']) or with the ``all`` shortcut. .. code-block:: ruby push.device_types = UA.all Delivery -------- Once you have set the ``audience``, ``notification``, and ``device_types`` attributes, the notification is ready for delivery. .. code-block:: ruby push.send_push If the delivery is unsuccessful, an :rb:class:`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. .. code-block:: ruby 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 :rb:class:`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. .. code-block:: ruby 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 :rb:class:`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. .. code-block:: ruby 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 :rb:class:`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. .. code-block:: ruby 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. .. code-block:: ruby 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: .. code-block:: ruby 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