# Ruby

URL: https://pieowl.com/docs/sdks/ruby





Pieowl doesn't ship a Ruby gem. You send events from Ruby with a plain HTTP request to the [Track API](/docs/api/track). The example below uses `Net::HTTP` from the standard library, so there is nothing to install.

Before you start [#before-you-start]

You need a client ID and a client secret. Find them in the dashboard under **Settings → Developers → Keys**. Server requests must include the secret, so keep it on your server and load it from an environment variable.

Send an event [#send-an-event]

Every request is a `POST` to `https://api.pieowl.com/track` with a JSON body of `{ "type": ..., "payload": ... }`.

```ruby title="pieowl.rb"
require "json"
require "net/http"

module Pieowl
  URL = URI("https://api.pieowl.com/track")

  def self.send_event(type, payload, client_ip: nil, user_agent: nil)
    headers = {
      "Content-Type" => "application/json",
      "pieowl-client-id" => ENV.fetch("PIEOWL_CLIENT_ID"),
      "pieowl-client-secret" => ENV.fetch("PIEOWL_CLIENT_SECRET")
    }
    # Optional: forward the visitor's IP and user agent for location and device data
    headers["pieowl-client-ip"] = client_ip if client_ip
    headers["user-agent"] = user_agent if user_agent

    response = Net::HTTP.post(URL, { type: type, payload: payload }.to_json, headers)
    response.is_a?(Net::HTTPSuccess)
  end
end
```

Usage [#usage]

Tracking events [#tracking-events]

```ruby
Pieowl.send_event("track", {
  name: "signup",
  profileId: "user_123", # optional
  properties: { plan: "pro" }
})
```

Identifying users [#identifying-users]

```ruby
Pieowl.send_event("identify", {
  profileId: "user_123", # required
  firstName: "Joe",
  lastName: "Doe",
  email: "joe@doe.com",
  properties: { tier: "premium" }
})
```

Incrementing and decrementing properties [#incrementing-and-decrementing-properties]

`value` is optional and defaults to 1.

```ruby
Pieowl.send_event("increment", { profileId: "user_123", property: "visits", value: 1 })
Pieowl.send_event("decrement", { profileId: "user_123", property: "credits", value: 1 })
```

Tracking revenue [#tracking-revenue]

A purchase is a `revenue` event with these properties:

* `__amount`: in normal units, like `49.99`, not cents.
* `__currency`: an ISO 4217 code, like `EUR`. Optional, your site currency by default.
* `__orderId`: your order number. The same order sent twice counts once.
* `__deviceId`: the visitor's device ID, from `pieowl.getDeviceId()` in the browser. The purchase is credited to their visit.

For a refund, send the same event with `__refund` set to true. Leave out `__amount` to refund the whole order. See [Revenue attribution](/docs/revenue-attribution).

```ruby
Pieowl.send_event("track", {
  name: "revenue",
  properties: { __amount: 49.99, __currency: "EUR", __orderId: "A-1001", __deviceId: device_id }
})

# Refund the whole order
Pieowl.send_event("track", {
  name: "revenue",
  properties: { __orderId: "A-1001", __refund: true }
})
```

Rails [#rails]

In a controller, pass the visitor's IP and user agent so Pieowl can show their location and device:

```ruby
class SignupsController < ApplicationController
  def create
    user = User.create!(user_params)
    Pieowl.send_event(
      "track",
      { name: "signup", profileId: user.id.to_s },
      client_ip: request.remote_ip,
      user_agent: request.user_agent
    )
    redirect_to dashboard_path
  end
end
```

For busy apps, send events from a background job (for example Active Job) so a slow request never holds up the response.

Good to know [#good-to-know]

* **Errors:** `send_event` returns `false` when Pieowl rejects a request, for example a bad client secret or an invalid payload. Network errors raise, so rescue them if analytics must never break a request.
* **More event types:** Groups and the full request schema are in the [Track API reference](/docs/api/track).