# Ruby Software Development Kit for Kevel Decision & UserDB APIs

- [Open Source on Github](https://github.com/adzerk/adzerk-decision-sdk-ruby)
- [RubyGem Package](https://rubygems.org/gems/adzerk_decision_sdk)

## Installation

Requires [Ruby 2.5](https://en.wikipedia.org/wiki/Ruby_(programming_language)#Table_of_versions) or higher.

```shell
 gem install adzerk_decision_sdk --pre
```

Or add to your `Gemfile`:

```ruby
 gem 'adzerk_decision_sdk', '~> 1.0.0-pre.beta.2'
```

## Examples

### Fetching an Ad Decision

```ruby
 require "adzerk_decision_sdk"

# Demo network, site, and ad type IDs; find your own via the Adzerk UI!
 client = AdzerkDecisionSdk::Client.new(network_id: 23, site_id: 667480)

request = {
   placements: [{ adTypes: [5] }],
   user: { key: "abc" },
   keywords: ["keyword1", "keyword2"],
 }

pp client.decisions.get(request)
```

### Recording Impression & Clicks

Use with the fetch ad example above.

```ruby
 # Impression pixel; fire when user sees the ad
 client.pixels.fire(decision.impression_url)

# Click pixel; fire when user clicks on the ad
 # status: HTTP status code
 # location: click target URL
 status, location = client.pixels.fire(decision.click_url)
```

### UserDB: Reading User Record

```ruby
 require "adzerk_decision_sdk"

# Demo network ID; find your own via the Adzerk UI!
 client = AdzerkDecisionSdk::Client.new(network_id: 23)
 pp client.user_db.read("abc")
```

### UserDB: Setting Custom Properties

```ruby
 require "adzerk_decision_sdk"

# Demo network ID; find your own via the Adzerk UI!
 client = AdzerkDecisionSdk::Client.new(network_id: 23)

props = {
   favoriteColor: "blue",
   favoriteNumber: 42,
   favoriteFoods: ["strawberries", "chocolate"],
 }

client.user_db.set_custom_properties("abc", props)
```

### UserDB: Forgetting User Record

```ruby
 require "adzerk_decision_sdk"

# Demo network ID and API key; find your own via the Adzerk UI!
 client = AdzerkDecisionSdk::Client.new(network_id: 23, api_key: ENV["ADZERK_API_KEY"])
 client.user_db.forget("abc")
```

### Decision Explainer

```ruby
 require "adzerk_decision_sdk"

# Demo network, site, and ad type IDs; find your own via the Adzerk UI!
 client = AdzerkDecisionSdk::Client.new(network_id: 23, site_id: 667480)

request = {
   placements: [{ adTypes: [5] }],
   user: { key: "abc" },
   keywords: ["keyword1", "keyword2"],
 }

options = {
   include_explanation: true,
   api_key: ENV["ADZERK_API_KEY"]
 }

pp client.decisions.get(request, options)
```