# Airship Ruby Library

Ruby library for using Airship's messaging platform and related features.
## Resources

- [GitHub Repo](https://github.com/urbanairship/ruby-library/)
- [rubygems.org](https://rubygems.org/gems/urbanairship/)
- [Airship API Reference](https://www.airship.com/docs/developer/rest-api/ua/)
- [Ruby Library API Reference](https://www.airship.com/docs/reference/libraries/ruby/latest)

## Installation

If you do not yet have the `bundler` gem, get it using:
**Install Bundler**

```bash
gem install bundler
```


Once you have the `bundler` gem, add this line to your application's
Gemfile:

**Install our gem**

```bash
gem 'urbanairship'
```


And then execute:

**Bundle**

```bash
bundle
```


Or install it yourself as:

**Alternative installation**

```bash
gem install urbanairship
```


## Configuration

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

```ruby
require 'urbanairship'

Urbanairship.configure do |config|
  config.server = 'api.asnapieu.com'
  config.oauth_server = 'oauth2.asnapieu.com'
  config.log_path = '/path/to/your/logfile'
  config.log_level = Logger::WARN
  config.timeout = 60
end
```


If you want to use a custom logger such as Rails.logger, you can do:

**Custom logger**

```ruby
require 'urbanairship'

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


### Available configurations

Allowances per configuration:

* log_path — Allows defining the folder where the log file will be created. The default is nil.
* log_level — Allows defining the log level. Only messages at that level or higher will be printed. The default is INFO.
* server — Allows defining the Airship server you want to use ("api.asnapieu.com" for EU or "api.asnapius.com" for US)
* oauth_server — Allows defining the Airship OAuth server you want to use. Use `oauth2.asnapieu.com` for EU or `oauth2.asnapius.com` for US.
* timeout — Allows defining the request timeout in seconds. The default is 5.

## Usage

Broadcast to all devices:

**Broadcast**

```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
```


Basic tag push:

**Tag push**

```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 server api.asnapius.com:

**Default server with Basic auth**

```ruby
require 'urbanairship'

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


You can change the server globally in the Urbanairship configuration:
**Using a different server**

```ruby
require 'urbanairship'

Urbanairship.configure do |config|
  config.server = 'api.asnapieu.com'
end

Urbanairship::Client.new(key:'application_key', secret:'master_secret')
# request will be sent to the 'api.asnapieu.com' server
```


### Using Bearer Token auth

**Bearer token authentication**

```ruby
require 'urbanairship'

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


### Using OAuth

**OAuth**

```ruby
require 'urbanairship'

UA = Urbanairship
app_key = 'application_key'

oauth = UA::Oauth.new(
  client_id: 'client_id',
  key: app_key,
  assertion_private_key: 'your_private_key',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)
airship = UA::Client.new(key: app_key, oauth: oauth)
# Then continue as you would otherwise
```


> **Note:** * You cannot use both OAuth and Bearer Token auth at the same time.
> * OAuth cannot be used with the older `api.urbanairship.com` and `api.airship.eu` base URLs. See [Base URL](https://www.airship.com/docs/developer/rest-api/ua/introduction/#servers) and [OAuth](https://www.airship.com/docs/developer/rest-api/ua/operations/oauth/) in the *Airship API* reference.
> * OAuth is not supported for all endpoints. See the [Airship API Authorization Reference](https://www.airship.com/docs/developer/rest-api/ua/api-auth-reference/).