urbanairship 3.0.2 → 3.1.0

data/docs/devices.rst

@@ -0,0 +1,54 @@
+Retrieving Device Information
+=============================
+
+Channel Listing
+---------------
+
+Device lists are fetched by instantiating an iterator object
+using :rb:class:`ChannelList`. For more information, see:
+http://docs.urbanairship.com/api/ua.html#channels
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    channel_list = UA::ChannelList.new(client: airship)
+
+    channel_list.each do |channel|
+        puts(channel)
+    end
+
+Channel Lookup
+--------------
+
+Device metadata is fetched for a specific channel by using
+:rb:class:`ChannelInfo` with the method ``lookup(uuid: 'uuid')``.
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    channel_client = UA::ChannelInfo.new(client: airship)
+    channel_info = channel_client.lookup(uuid: 'uuid')
+    puts(channel_info)
+
+Feedback
+--------
+
+Feedback returns a list of dictionaries of device tokens/APIDs that the
+respective push provider has told us are uninstalled since the given
+timestamp. For more information, see:
+http://docs.urbanairship.com/api/ua.html#feedback
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    require 'time'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    since = (Time.now.utc - (60 * 60 * 24 * 3)).iso8601
+    feedback = UA::Feedback.new(client: airship)
+    tokens = feedback.device_token(since: since)
+    apids = feedback.apid(since: since)

data/docs/examples.rst

@@ -0,0 +1,118 @@
+Examples
+========
+
+Common setup:
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key: 'app_key', secret: 'master_secret')
+
+
+Simple broadcast to all devices
+-------------------------------
+
+.. code-block:: ruby
+
+    push = airship.create_push
+    push.audience = UA.all
+    push.notification = UA.notification(alert: "Hello, world!")
+    push.device_types = UA.all
+    push.send_push
+
+
+Complex audience with platform specifics
+---------------------------------------------
+
+.. code-block:: ruby
+
+    push = airship.create_push
+    push.audience = UA.and(
+        UA.tag("breakingnews"),
+        UA.or(
+            UA.tag("sports"),
+            UA.tag("worldnews")
+        )
+    )
+    push.notification = UA.notification(
+        ios: UA.ios(
+            alert: "Kim Jong-Un wins U.S. Open",
+            badge: "+1",
+            extra: {"articleid" => "123456"}
+        ),
+        android: UA.android(
+            alert: "Breaking Android News! Glorious Leader Kim Jong-Un wins U.S. Open!",
+            extra: {"articleid" => "http://m.example.com/123456"}
+        ),
+        amazon: UA.amazon(
+            alert: 'Breaking Amazon News!',
+            expires_after: 60,
+            extra: {'articleid' => '12345'},
+            summary: 'This is a short message summary',
+        )
+    )
+    push.device_types = UA.device_types(['ios', 'android', 'amazon'])
+    push.send_push
+
+
+Single iOS push
+---------------
+
+.. code-block:: ruby
+
+    push = airship.create_push
+    push.audience = UA.ios_channel('channel-id')
+    push.notification = UA.notification(
+       ios: UA.ios(alert="Kim Jong-Un is following you on Twitter")
+    )
+    push.device_types = UA.device_types(['ios'])
+    push.send_push
+
+
+Single iOS Rich Push with notification
+--------------------------------------
+
+.. code-block:: ruby
+
+    push = airship.create_push
+    push.audience = UA.ios_channel('channel-id')
+    push.notification = UA.notification(
+       ios: UA.ios(alert="Kim Jong-Un is following you on Twitter")
+    )
+    push.device_types = UA.device_types(['ios'])
+    push.message = UA.message(title: "New follower", body: "<h1>OMG It's Kim Jong-Un</h1>")
+    push.send_push
+
+
+Rich Push with extra and without notification
+---------------------------------------------
+
+.. code-block:: ruby
+
+    push = airship.create_push
+    push.audience = UA.all
+    push.device_types = UA.all
+    push.message = UA.message(
+      title: "New follower",
+      body: "<h1>OMG It's Kim Jong-Un</h1>",
+      extra: {"articleid" => "http://m.example.com/123456"}
+    )
+    push.send_push
+
+
+Scheduled iOS Push
+------------------
+
+.. code-block:: ruby
+
+    sched = airship.create_scheduled_push
+    sched.schedule = UA.scheduled_time(Time.now.utc + 60)
+
+    sched.push = airship.create_push
+    sched.push.audience = UA.ios_channel('channel-id')
+    sched.push.notification = UA.notification(
+       ios: UA.ios(alert: "Kim Jong-Un is following you on Twitter"))
+    sched.push.device_types = UA.device_types(['ios'])
+
+    sched.send_push

data/docs/exceptions.rst

@@ -0,0 +1,17 @@
+Exceptions
+==========
+
+AirshipFailure
+--------------
+
+Raised when there is an error response from the server that is not a 401 or 403 error.
+
+Forbidden
+---------
+
+Raised when there is a 403 error response from the server.
+
+Unauthorized
+------------
+
+Raised when there is a 401 error response from the server.

data/docs/index.rst

@@ -0,0 +1,83 @@
+Urban Airship Ruby Library
+==========================
+
+``urbanairship`` is a Ruby library for using the `Urban Airship
+<http://urbanairship.com/>`_ web service API for push notifications and
+rich app pages.
+
+
+Installation
+------------
+
+If you have the ``bundler`` gem (if not you can get it with ``$ gem install bundler``) add this line to your application's Gemfile::
+
+    >>> gem 'urbanairship'
+
+And then execute::
+
+    >>> $ bundle
+
+OR install it yourself as::
+
+    >>> gem install urbanairship
+
+
+Using the library
+-----------------
+
+The library is intended to be used with the small footprint of a single
+import. To get started, import the package, and create an
+:rb:class:`Airship` object representing a single UA application.
+
+Note that channels are preferred over ``device_token`` and ``apid``. See:
+`documentation on channels <channels>`_.
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    p = airship.create_push
+    p.audience = UA.all
+    p.notification = UA.notification(alert: 'Hello')
+    p.device_types = UA.all
+    p.send_push
+
+The library uses `unirest`_ for communication with the UA API.
+
+
+Development
+-----------
+
+The library source code is `available on GitHub <github>`_.
+
+Tests can be run with rspec_:
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   push.rst
+   segment.rst
+   devices.rst
+   channel_uninstall.rst
+   tags.rst
+   named_user.rst
+   reports.rst
+   exceptions.rst
+   examples.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+.. _channels: http://docs.urbanairship.com/topic-guides/channels.html
+.. _unirest: http://unirest.io/ruby.html
+.. _github: https://github.com/urbanairship/ruby-library
+.. _rspec: https://nose.readthedocs.org/en/latest/

data/docs/named_user.rst

@@ -0,0 +1,101 @@
+Named User
+==========
+
+Named User Listing
+------------------
+
+Named User lists are fetched by instantiating an iterator object
+using :rb:class:`NamedUserList`.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#listing>`__
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    named_user_list = UA::NamedUserList.new(client: airship)
+
+    named_user_list.each do |named_user|
+        puts(named_user)
+    end
+
+Association
+-----------
+
+Associate a channel with a named user ID. For more information, see
+`the API documentation
+<http://docs.urbanairship.com/api/ua.html#association>`__
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    named_user = UA::NamedUser.new(client: airship)
+    named_user.named_user_id = 'named_user'
+    named_user.associate(channel_id: 'channel_id', device_type: 'ios')
+
+.. note::
+
+    You may only associate up to 20 channels to a Named User.
+
+Disassociation
+--------------
+
+Remove a channel from the list of associated channels for a named user.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#disassociation>`__
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    named_user = UA::NamedUser.new(client: airship)
+    named_user.disassociate(channel_id: 'channel_id', device_type: 'ios')
+
+.. note::
+
+    ``named_user_id`` does not have to be set on the named_user object for this
+    method call since ``channel_id`` can only be associated with one named user.
+
+Lookup
+------
+
+Look up a single named user.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#lookup>`__
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    named_user = UA::NamedUser.new(client: airship)
+    named_user.named_user_id = 'named_user'
+    user = named_user.lookup
+
+Tags
+----
+
+Add, remove, or set tags on a named user. For more information,
+see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#tags-named-users>`__
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    named_user_tags = UA::NamedUserTags.new(client: airship)
+    named_user_ids = ['named_user_id1', 'named_user_id2', 'named_user_id3']
+    named_user_tags.set_audience(user_ids: named_user_ids)
+    named_user_tags.add(group_name: 'group_name1', tags: ['tag1', 'tag2', 'tag3'])
+    named_user_tags.remove(group_name: 'group_name2', tags: 'tag4')
+    named_user_tags.send_request
+
+.. note::
+
+    A single request may contain an add or remove field, both, or a single set
+    field.

data/docs/push.rst

@@ -0,0 +1,416 @@
+Defining and Sending Push Notifications
+=======================================
+
+The Urban 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 iOS device token:
+
+.. code-block:: ruby
+
+    push.audience = UA.device_token(token)
+
+Select a single BlackBerry PIN:
+
+.. code-block:: ruby
+
+    push.audience = UA.device_pin(pin)
+
+Select a single Android APID:
+
+.. code-block:: ruby
+
+    push.audience = UA.apid(uuid)
+
+Select a single Windows 8 APID:
+
+.. code-block:: ruby
+
+    push.audience = UA.wns(uuid)
+
+Select a single Windows Phone 8 APID:
+
+.. code-block:: ruby
+
+    push.audience = UA.mpns(uuid)
+
+Select a single tag:
+
+.. code-block:: ruby
+
+    push.audience = UA.tag(tag)
+
+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 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.urbanairship.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 payload with platform-specific values as well.
+
+.. code-block:: ruby
+
+    push.notification = UA.ios(
+        alert: 'hello world',
+        badge: 123,
+        sound: 'sound file',
+        extra: { 'key' => 'value', 'key2' => 'value2' }
+        expiry: '2012-01-01 12:45',
+        category: 'category_name',
+        interactive: UA.interactive(
+            type: 'ua_share',
+            button_actions: {
+                share: { share: 'Sharing is caring!' }
+            }
+        ),
+        content_available: true
+    )
+
+    push.notification = UA.amazon(
+        alert: 'hello world',
+        consolidation_key: 'key',
+        expires_after: '2012-01-01 12:45',
+        extra: { 'key' => 'value', 'key2' => 'value2' },
+        title: 'title',
+        summary: 'summary',
+        interactive: UA.interactive(
+            type: 'ua_share',
+            button_actions: {
+                share: { share: 'Sharing is caring!' }
+            }
+        )
+    )
+
+    push.notification = UA.android(
+        alert: 'hello world',
+        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!' }
+            }
+        )
+    )
+
+    push.notification = UA.blackberry(
+        alert: 'hello world',
+        body: 'body',
+        content_type: 'text/plain'
+    )
+
+    push.notification = UA.wns_payload(
+        alert: 'hello world',
+        tile: nil,
+        toast: nil,
+        badge: nil
+    )
+
+    push.notification = UA.mpns_payload(
+        alert: 'hello world',
+        tile: nil,
+        toast: nil,
+        badge: nil
+    )
+
+.. note::
+    The input for wns_payload must include exactly one of
+    alert, toast, tile, or badge.
+
+    The input for mpns_payload must include exactly one of
+    alert, toast, or tile.
+
+Actions
+-------
+
+Urban 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.urbanairship.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 Urban Airship!',
+        open_: {
+            type: 'url',
+            content: 'http://www.urbanairship.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.urbanairship.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', 'blackberry'])
+
+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.
+
+
+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(airship, url)
+   # change scheduled time to tomorrow
+   schedule.schedule = UA.scheduled_time(Time.now.utc + (60 * 60 * 24))
+   schedule.update
+
+   # Cancel
+   schedule.cancel