Ruby SDK: send and verify Meta conversions

plainrouter-sdk is the official Ruby SDK for Plainrouter’s signed OpenAPI contract. Gem 0.5.0 targets signed API contract 0.5.0 and exposes a compact client over the generated API. The source is in plainrouter/sdk. Review release notes before upgrading while the gem remains in the 0.x series.

Requirements

Ruby 3.2 or newer.
A Signals workspace secret for production Conversion API operations.
Server-side code. Do not put the secret in browser or distributed client code.

Install

Install plainrouter-sdk 0.5.0:

gem install plainrouter-sdk -v 0.5.0

Or add the gem to your Gemfile, then run bundle install:

gem "plainrouter-sdk", "~> 0.5.0"

Create an authenticated client

Pass the Signals workspace secret when you create the client:

require "plainrouter"

client = PlainRouter::Client.new(
  token: ENV.fetch("PLAINROUTER_TOKEN")
)

events = client.operations.list_events(per_page: 25)

The client sends the Signals workspace secret as a bearer token. It does not read credentials from the environment automatically.

Send a Meta conversion

This recipe calls Plainrouter’s Conversion API, not Meta Graph API directly. Before sending a real purchase, connect a Meta destination and read the actual payment and advertising-consent records from your application. Keep Ruby as the purchase owner; do not also send this purchase through the managed browser or Stripe settlement flow. The function takes your persisted order ID, original payment time, decimal amount, currency, and consent snapshot. paid_at and consent_captured_at are Ruby Time objects. The consent hash uses symbol keys matching the three API consent fields. Replace the source URL with your checkout URL.

require "time"

def send_purchase(client, order_id:, paid_at:, value:, currency:,
                  consent:, consent_captured_at:)
  grants = %i[ad_storage ad_user_data ad_personalization]
  unless grants.all? { |field| consent[field] == "granted" }
    raise ArgumentError, "Recorded advertising consent is required"
  end
  raise ArgumentError, "A stable order ID is required" if order_id.to_s.empty?

  body = {
    event_id: "purchase:#{order_id}",
    event_name: "Purchase",
    event_time: paid_at.to_i,
    event_source: "https://shop.example/checkout/success",
    action_source: "website",
    consent_basis: "consent",
    consent: {
      ad_storage: consent.fetch(:ad_storage),
      ad_user_data: consent.fetch(:ad_user_data),
      ad_personalization: consent.fetch(:ad_personalization),
      captured_at: consent_captured_at.iso8601,
      source: "checkout_cmp"
    },
    value_data: { value: value, currency: currency, order_id: order_id }
  }

  receipt, status, _headers = client.events.create_event_with_http_info(body)
  { event_id: receipt.event_id, duplicate: receipt.duplicate, status: status }
rescue PlainRouter::OpenAPI::ApiError => error
  # Keep credentials and customer payloads out of logs.
  raise "Plainrouter rejected the request (HTTP #{error.code})"
end

A new event returns status: 202; a retry of the same event ID returns status: 200 and duplicate: true. Persist the payload before sending, and reuse its ID and original payment time after an uncertain timeout. Check that advertising use remains permitted before a later retry. Duplicate ingestion does not resend a failed Meta delivery or update the original event.

How do I confirm delivery?

Use the returned receipt ID to read the event. This function returns delivery statuses without logging identity fields:

def delivery_statuses(client, event_id)
  trace = client.events.get_event(event_id)
  trace.deliveries.map { |delivery| delivery.status }
end

accepted means Meta accepted a delivery. queued, sent, or retrying means its outcome is pending. An empty list proves no delivery acceptance; inspect the destination and event eligibility. Meta acceptance does not prove ad attribution. See all delivery statuses.

Handle API failures

Result	Action
`401`	Stop retries and check the Signals workspace secret and workspace.
`404` when reading	Check the event ID, workspace scope, and retention.
`422`	Correct the field errors in `ApiError#response_body`; check consent, timestamps, and decimal-string values.
Network timeout	The request may have been accepted. Retry the persisted payload with the same event ID.

Inspect validation details in a controlled development environment. Do not log the complete exception or response body in production; it can include request-related details. Generated Ruby models do not replace server-side validation.

Choose an API group

Group	Use it for
`client.events`	Create or retrieve an event and verify Signal ingestion.
`client.operations`	List events, control destination testing, replay deliveries, read reports, or delete user data.
`client.sandbox`	Discover and validate identity-free synthetic requests without a production credential.

Generated models, API errors, configuration, response metadata, and every generated operation remain available under PlainRouter::OpenAPI.

Verify Signal ingestion

result = client.events.verify_signal_ingestion

The operation is idempotent. A repeated verification returns the existing event with duplicate: true. The event confirms ledger receipt but is not real arrival evidence and does not complete onboarding.

Try the zero-auth sandbox

Create a client without a token for sandbox discovery:

sandbox = PlainRouter::Client.new
example = sandbox.sandbox.get_sandbox

Sandbox operations accept only identity-free synthetic data. They do not read or write the production Signal ledger and do not contact an advertising provider. Read Try the API without an account before submitting a synthetic request.

Configure another API origin or timeout

The default API base URL is https://plainrouter.com/api/v1 and the default timeout is 30 seconds. Override either value only for a Plainrouter-provided region or a controlled test environment:

client = PlainRouter::Client.new(
  token: ENV.fetch("PLAINROUTER_TOKEN"),
  base_url: "https://example.test/api/v1",
  timeout: 20
)

Handle credentials safely

The Ruby SDK accepts a Signals workspace secret for production Conversion API calls. It does not accept an MCP workspace execution token or OAuth management credential. Keep the secret in server-side credential storage. Never include it in prompts, URLs, logs, source control, or client-side code. For request and response fields, use the Conversion API reference.

Overview

SDKs

Recipes

Ruby SDK: send and verify Meta conversions

Requirements

Install

Create an authenticated client

Send a Meta conversion

How do I confirm delivery?

Handle API failures

Choose an API group

Verify Signal ingestion

Try the zero-auth sandbox

Configure another API origin or timeout

Handle credentials safely

​Requirements

​Install

​Create an authenticated client

​Send a Meta conversion

​How do I confirm delivery?

​Handle API failures

​Choose an API group

​Verify Signal ingestion

​Try the zero-auth sandbox

​Configure another API origin or timeout

​Handle credentials safely

Requirements

Install

Create an authenticated client

Send a Meta conversion

How do I confirm delivery?

Handle API failures

Choose an API group

Verify Signal ingestion

Try the zero-auth sandbox

Configure another API origin or timeout

Handle credentials safely