pieowlDocs
pieowl.comSign inStart free trial
Ruby

Ruby

Send events to Pieowl from Ruby and Rails with the HTTP API. Track events, identify users and record revenue with Net::HTTP.

View as Markdown

Pieowl doesn't ship a Ruby gem. You send events from Ruby with a plain HTTP request to the Track API. The example below uses Net::HTTP from the standard library, so there is nothing to install.

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

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

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

Tracking events

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

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

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

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.

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

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

  • 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.