RubyDoc.info: File: README – Documentation for urbanairship (9.2.0)

.. image: github.com/urbanairship/ruby-library/actions/workflows/ci.yaml/badge.svg

:target: https://github.com/urbanairship/ruby-library/

About

“urbanairship“ is a Ruby library for using the ‘Airship <airship.com/>`_ REST API for push notifications, message center messages, email, and SMS.

Requirements

We officially support the following Ruby versions: 2.6.7 2.7.2

Newer 2.x versions should work as well.

Functionality

Version 8.0 is a major upgrade, as we have changed the tested/supported versions of Ruby. A more detailed list of changes can be found in the CHANGELOG.

Questions

The best place to ask questions or report a problem is our support site: support.airship.com/

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:

.. code-block: >>> $ gem ‘urbanairship’

And then execute:

.. code-block: >>> $ bundle

OR install it yourself as:

.. code-block: >>> $ gem install urbanairship

Configuration

In your app initialization, you can do something like the following:

.. code-block: ruby

require 'urbanairship'

Urbanairship.configure do |config|
  config.server = 'go.airship.eu'
  config.log_path = '/path/to/your/logfile'
  config.log_level = Logger::WARN
  config.timeout = 60
end

If you want to use a custom logger (e.g Rails.logger), you can do:

.. code-block: ruby

require 'urbanairship'

Urbanairship.configure do |config|
  config.custom_logger = Rails.logger
  config.log_level = Logger::WARN
end

Available Configurations

log_path: Allows to define the folder where the log file will be created (the default is nil).
log_level: Allows to define the log level and only messages at that level or higher will be printed (the default is INFO).
server: Allow to define the Airship server you want to use (“go.airship.eu” or “go.urbanairship.com”)
timeout: Allows to define the request timeout in seconds (the default is 5).

Usage

Once the gem has been installed you can start sending pushes! See the ‘full documentation <docs.airship.com/reference/libraries/ruby>`_, `api examples <docs.airship.com/topic-guides/api-examples.html>`_, as well as the `Airship API Documentation <docs.airship.com/api/>`_ for more information.

Broadcast to All Devices

.. 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.device_types(['ios','android'])
p.send_push

Simple Tag Push

.. code-block: ruby

require 'urbanairship'

UA = Urbanairship

airship = UA::Client.new(key:'application_key', secret:'master_secret')
p = airship.create_push
p.audience = UA.tag('some_tag')
p.notification = UA.notification(alert: 'Hello')
p.device_types = UA.device_types(['ios','android'])
p.send_push

Specify the Airship server used to make your requests

By default, the request will be sent to the ‘go.urbanairship.com’ server:

.. code-block: ruby

require 'urbanairship'

Urbanairship::Client.new(key:'application_key', secret:'master_secret')

You can change the server globally in the Urbanairship configuration:

.. code-block: ruby

require 'urbanairship'

Urbanairship.configure do |config|
  config.server = 'go.airship.eu'
end

Urbanairship::Client.new(key:'application_key', secret:'master_secret')
# request will be sent to the 'go.airship.eu' server

Finally, you can change the targeted server on a request basis:

.. code-block: ruby

require 'urbanairship'

Urbanairship.configure do |config|
  config.server = 'go.airship.eu'
end

Urbanairship::Client.new(key:'application_key', secret:'master_secret', server: 'go.urbanairship.com')
# The Urbanairship configuration is overridden by the client and the
# request will be sent to the 'go.urbanairship.com' server

Using Bearer Token Auth

.. code-block: ruby

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key:'application_key', token:'token')
# Then continue as you would otherwise

Note: If you include a token in your instantiation, the request will use bearer token auth. Bearer token auth is required for some endpoints, but not supported by others. Please check ‘the Airship docs site <docs.airship.com/>`_ to see where it is supported.

Contributing

Fork it ( github.com/urbanairship/ruby-library )
Create your feature branch: “git checkout -b my-new-feature“
Commit your changes “git commit -am ‘Add some feature’“
Push to the branch “git push origin my-new-feature“
Create a new Pull Request
Sign Airship’s ‘contribution agreement <docs.google.com/forms/d/e/1FAIpQLScErfiz-fXSPpVZ9r8Di2Tr2xDFxt5MgzUel0__9vqUgvko7Q/viewform>`_.
Reach out to our support team at support.airship.com to let

us know about your PR and your urgency level.

Note: Changes will not be approved and merged without a signed contribution agreement.

Development

After checking out the repo, ensure you have “bundler“ installed

(“$ gem install bundler“) run: >>> $ bin/setup
to install dependencies. Then, run: >>> $ bin/console

for an interactive prompt that will allow you to experiment.

OR you can build a local gem to play with: >>> $ gem build urbanairship.gemspec >>> $ gem install ./urbanairship-<VERSION>.gem

Having a local build will give you better logging if you are running into issues, but be careful to make sure to use our released public gem in Production.