urbanairship 3.0.2 → 3.1.0

data/docs/reports.rst

@@ -0,0 +1,303 @@
+*******
+Reports
+*******
+
+Individual Push Response Stats
+==============================
+
+Returns detailed report information about a specific push notification.
+Use the push_id, which is the identifier returned by the API that represents a
+specific push message delivery.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#individual-push-response-statistics>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    d = UA::IndividualResponseStats.new(client: airship)
+    statistics = d.get(push_id: 'push_id')
+
+
+Devices Report 
+==============
+
+Returns an app’s opted-in and installed device counts broken out by device
+type. This endpoint returns the same data that populates the Devices Report.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#devices-report-api>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    d = UA::DevicesReport.new(client: airship)
+    devices = d.get(date: '2015/08/01')
+
+
+Push Report
+===========
+
+Get the number of pushes you have sent within a specified time period.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#push-report>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    listing = UA::PushList.new(
+        client: airship,
+        start_date: '2015/06/01',
+        end_date: '2015/08/01',
+        precision: 'HOURLY'
+    )
+    listing.each do |resp|
+        puts(resp)
+    end
+
+.. note::
+    precision needs to be a member of ['HOURLY', 'DAILY', 'MONTHLY']
+
+
+
+Per Push Reporting
+==================
+
+Retrieve data specific to the performance of an individual push.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#per-push-reporting>`_
+
+---------------
+Per Push Detail
+---------------
+
+
+Single Request
+--------------
+
+Get the analytics detail for a specific Push ID. For more information, see `the
+API documentation
+<http://docs.urbanairship.com/api/ua.html#single-request>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    d = UA::PerPushDetail.new(client: airship)
+    details = d.get_single(push_id:'push_id')
+
+
+Batch Request
+-------------
+
+Get the analytics details for an array of Push IDs. For more information,
+see `the API documentation <http://docs.urbanairship.com/api/ua.html#batch-request>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    d = UA::PerPushDetail.new(client: airship)
+    details = d.get_batch(push_ids: ['push_id', 'push_id2', 'push_id3'])
+
+.. note::
+
+    There is a maximum of 100 Push IDs per request
+
+---------------
+Per Push Series
+---------------
+
+Get the default time series data. For more information,
+see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#per-push-series>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    s = UA::PerPushSeries.new(client: airship)
+    series = s.get(
+        push_id: 'push_id',
+        precision: 'HOURLY',
+        start_date: '2015-06-01',
+        end_date: '2015-08-01'
+    )
+
+.. note::
+
+    precision, start_date, and end_date are optional parameters. However, if specifying
+    a date range, precision, start_date and end_date must all be specified. Precision
+    can be specified without start_date and end_date but must be a member of
+    ['HOURLY', 'DAILY', 'MONTHLY'].
+
+Response Report
+===============
+
+Get the number of direct and influenced opens of your app. For more 
+information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#response-report>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    listing = UA::ResponseReportList.new(
+        client: airship,
+        start_date: '2015-06-01',
+        end_date: '2015-08-01',
+        precision: 'MONTHLY'
+    )
+    listing.each do |resp|
+        puts(resp)
+    end
+
+.. note::
+
+    precision needs to be a member of ['HOURLY', 'DAILY', 'MONTHLY']
+
+
+Response Listing
+================
+
+Get a listing of all pushes and basic response information in a given
+timeframe by instantiating an iterator object using ResponseList. 
+Start and end date times are required parameters.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#response-listing>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    response_list = UA::ResponseList.new(
+        client: airship,
+        start_date: '2015-06-01',
+        end_date: '2015-08-01,
+        limit: 20,
+        push_id_start: 'start_id'
+    )
+    response_list.each do |resp|
+        puts(resp)
+    end
+
+.. note::
+
+    limit (optional) is the number of results desired per page.
+    push_id_start (optional) specifies the id of the first response to return.
+
+
+App Opens Report
+================
+
+Get the number of users who have opened your app within the specified time 
+period. For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#app-opens-report>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    listing = UA::AppOpensList.new(
+        client: airship,
+        start_date: '2015-06-01',
+        end_date: '2015-08-01',
+        precision: 'HOURLY')
+    listing.each do |app_opens|
+        puts(app_opens)
+    end
+
+.. note::
+
+    precision needs to be a member of ['HOURLY', 'DAILY', 'MONTHLY']
+
+
+Time In App Report
+==================
+
+Get the average amount of time users have spent in your app within the 
+specified time period. For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#time-in-app-report>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    listing = UA::TimeInAppList.new(
+        client: airship,
+        start_date: '2015-06-01',
+        end_date: '2015-08-01',
+        precision: 'HOURLY')
+    listing.each do |time_in_app|
+        puts(time_in_app)
+    end
+
+.. note::
+
+    precision needs to be a member of ['HOURLY', 'DAILY', 'MONTHLY']
+
+
+Opt-In Report
+=============
+
+Get the number of opted-in push users who access the app within the specified 
+time period.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#opt-in-report>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    listing = UA::OptInList.new(
+        client: airship,
+        start_date: '2015-06-01',
+        end_date: '2015-08-01',
+        precision: 'HOURLY')
+    listing.each do |opt_ins|
+        puts(opt_ins)
+    end
+
+.. note::
+
+    precision needs to be a member of ['HOURLY', 'DAILY', 'MONTHLY']
+
+
+Opt-Out Report
+==============
+
+Get the number of opted-out push users who access the app within the specified 
+time period.
+For more information, see `the API documentation
+<http://docs.urbanairship.com/api/ua.html#opt-out-report>`_
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    listing = UA::OptOutList.new(
+        client: airship,
+        start_date: '2015-06-01',
+        end_date: '2015-08-01',
+        precision: 'HOURLY')
+    listing.each do |opt_outs|
+        puts(opt_outs)
+    end
+
+.. note::
+
+    precision needs to be a member of ['HOURLY', 'DAILY', 'MONTHLY']
+

data/docs/segment.rst

@@ -0,0 +1,97 @@
+########
+Segments
+########
+
+
+***************
+Segment Listing
+***************
+
+Segment lists are fetched by instantiating an iterator object using ``SegmentList``. For more
+information, see `the API documentation <http://docs.urbanairship.com/api/ua.html#segments>`__
+
+.. sourcecode:: ruby
+
+   require 'urbanairship'
+   UA = Urbanairship
+   airship = UA::Client.new(key: 'application_key', secret: 'master_secret')
+   segment_list = UA::SegmentList.new(client: airship)
+
+   segment_list.each do |segment|
+      puts(segment['display_name'])
+   end
+
+******************
+Creating a Segment
+******************
+
+Create a segment for the application. See the segment creation `API documentation
+<http://docs.urbanairship.com/api/ua.html#segment-creation>`__ for more information.
+
+.. sourcecode:: ruby
+
+   require 'urbanairship'
+   UA = Urbanairship
+   airship = UA::Client.new(key: 'application_key', secret: 'master_secret')
+   segment = UA::Segment.new(client: airship)
+   segment.display_name = 'Display Name'
+   segment.criteria = { 'tag' => 'existing_tag' }
+   segment.create
+
+
+*******************
+Modifying a Segment
+*******************
+
+Change the display name and/or criteria of a segment. For more information, see the segment
+update `API documentation <http://docs.urbanairship.com/api/ua.html#update-segment>`__.
+
+.. sourcecode:: ruby
+
+   require 'urbanairship'
+   UA = Urbanairship
+   airship = UA::Client.new(key: 'application_key', secret: 'master_secret')
+   segment = UA::Segment.new(client: airship)
+   segment.from_id(id: 'segment_id')
+   segment.display_name = 'Updated Display Name'
+   segment.criteria = { 'tag' => 'updated_tag' }
+   segment.update
+
+
+******************
+Deleting a Segment
+******************
+
+Delete a segment. For more information, see the segment deletion `API documentation
+<http://docs.urbanairship.com/api/ua.html#delete-segment>`__.
+
+.. sourcecode:: ruby
+
+   require 'urbanairship'
+   UA = Urbanairship
+   airship = UA::Client.new(key: 'application_key', secret: 'master_secret')
+   segment = UA::Segment.new(client: airship)
+   segment.from_id(id: 'segment_id')
+   segment.delete
+
+
+**************
+Segment Lookup
+**************
+
+Fetch a particular segment's display name and criteria. See the individual segment lookup
+`API documentation <http://docs.urbanairship.com/api/ua.html#individual-segment-lookup>`__ for
+more information.
+
+.. sourcecode:: ruby
+
+   require 'urbanairship'
+   UA = Urbanairship
+   airship = UA::Client.new(key: 'application_key', secret: 'master_secret')
+   segment = UA::Segment.new(client: airship)
+   segment.from_id(id: 'segment_id')
+
+.. note::
+
+   Calling ``segment.from_id(id: 'segment_id')`` automatically sets the ``display_name`` and
+   ``criteria`` attributes of segment.

data/docs/tags.rst

@@ -0,0 +1,49 @@
+Tags
+====
+
+This reference covers tag operations on channels.
+
+For more information, see: http://docs.urbanairship.com/api/ua.html#tags.
+
+
+ChannelTags
+-----------
+
+Allows the addition, removal, and setting of tags on a channel specified by
+the required audience field.
+
+A single request body may contain an add or remove
+field, or both, or a single set field. If both add and remove are fields are
+present and the intersection of the tags in these fields is not empty, then
+a 400 will be returned.
+
+Tag set operations only update tag groups that are present in the request.
+Tags for a given Tag Group can be cleared by sending a set field with an empty
+list.
+
+If a tag update request contains tags in multiple Tag Groups, the request
+will be accepted if at least one of the Tag Groups is active. If inactive or
+missing Tag Groups are specified, a warning will be included in the response.
+
+.. code-block:: ruby
+
+    require 'urbanairship'
+    UA = Urbanairship
+    airship = UA::Client.new(key:'application_key', secret:'master_secret')
+    channel_tags = UA::ChannelTags.new(client: airship)
+    ios_audience = ['channel1', 'channel2', 'channel3']
+    android_audience = 'channel4'
+    amazon_audience = nil
+    channel_tags.set_audience(
+        ios: ios_audience,
+        android: android_audience,
+        amazon: amazon_audience
+    )
+    channel_tags.add(group_name: 'group_name', tags: ['tag1', 'tag2', 'tag3'])
+    channel_tags.remove(group_name: 'group_name', tags: 'tag4')
+    channel_tags.send_request
+
+.. note::
+
+    The audience can be either a single channel or a list of channels. Similarly,
+    the tags can either be set as a single tag or a list of tags.