Ruby gem
The apps_patrol gem for Rails and Ruby Shopify apps.
apps_patrol sends usage events and shop profiles from a Ruby or Rails Shopify app. Calls return immediately; a background thread sends batches with retries. It has no dependencies beyond the standard library and needs Ruby 3.2 or newer.
Status
Version 0.2.0. It is not on RubyGems yet; install it from the repository.
Install
# Gemfile
gem "apps_patrol", git: "https://github.com/MahdiKetata99/apps-patrol-ruby.git"
Configure
# config/initializers/apps_patrol.rb
AppsPatrol.configure do |config|
config.api_key = ENV["APPS_PATROL_KEY"]
config.base_url = "https://www.apps-patrol.com"
config.enabled = Rails.env.production?
config.on_error = ->(error, context) { Rails.error.report(error, context: context) }
end
| Option | Default | Description |
|---|---|---|
api_key | ENV["APPS_PATROL_KEY"] | The app's ingest key. Without it every call is a no-op and one warning is logged. |
base_url | ENV["APPS_PATROL_URL"], else http://localhost:3000 | Your Apps Patrol address. |
enabled | true | false turns every call into a no-op. |
auto_app_opened | true | Under Rails, send app_opened once per shop per day. See Events. |
logger | Rails.logger, else standard error | Where problems are logged. nil silences it. |
on_error | none | Called with (error, context) for anything that could not be sent. |
batch_size | 100 | Send as soon as this many items are waiting (1 to 100). |
flush_interval | 2 | Send at least this often, in seconds. |
max_queue | 10000 | Items kept in memory while the server is unreachable. Beyond this the oldest are dropped. |
max_retries | 5 | Attempts per request for network errors, server errors and rate limiting. |
open_timeout, read_timeout | 3, 5 | Seconds allowed to connect and to wait for a response. |
Check your setup
AppsPatrol.ping
# => {"ok"=>true, "app"=>{"name"=>"Cart Holder", …}, "usage"=>{"events_this_month"=>12, "events_limit"=>250000}}
ping is the one call that raises: AppsPatrol::Error with code and status for a rejected key, or a message naming the address when the server cannot be reached. Run it from a console or a deploy check.
Track events
AppsPatrol.track(shop: "example.myshopify.com", event: "reservation_created", properties: { items: 3 })
Optional arguments: event_id: (defaults to a random UUID; pass your own to make a retry idempotent) and occurred_at: (defaults to now).
Standard events
AppsPatrol.onboarding_started(shop: shop)
AppsPatrol.onboarding_completed(shop: shop, steps: 3)
AppsPatrol.feature_used(shop: shop, feature: "bulk_edit")
AppsPatrol.plan_viewed(shop: shop)
AppsPatrol.upgrade_clicked(shop: shop, plan: "pro")
AppsPatrol.limit_reached(shop: shop, limit: "products")
AppsPatrol.error_shown(shop: shop, code: "sync_failed")
AppsPatrol.app_opened(shop: shop) # sent for you under Rails
Extra keyword arguments become properties. These names are a convention; track accepts any name.
Identify a shop
AppsPatrol.identify(
shop: "example.myshopify.com",
name: "Example Store", country: "DE", shopify_plan: "basic",
source: "app_store", utm: { utm_source: "newsletter" }
)
Accepts every field of the Shops API. Call it after install or sign-in.
In a Rails app with shopify_app
Loading the gem adds two things to your controllers:
- Automatic
app_openedfor the shop of the current Shopify session. track_patrol_event, which tracks for that shop:class ProductsController < AuthenticatedController def bulk_update # … track_patrol_event "feature_used", feature: "bulk_edit", items: params[:ids].size end end
Identify the shop after authentication:
# config/initializers/shopify_app.rb
ShopifyApp.configure do |config|
config.after_authenticate_job = { job: "IdentifyShopJob", inline: false }
end
class IdentifyShopJob < ApplicationJob
def perform(shop_domain:)
AppsPatrol.identify(shop: shop_domain, source: "app_store")
end
end
If your controllers find the shop another way, override patrol_shop_domain to return its myshopify.com domain.
How sending works
- Queued:
trackandidentifyadd to an in-memory queue and return. They never raise and never wait for the network. - Batched: a background thread sends up to 100 events per request, when a batch is full or every
flush_intervalseconds. - Retried: network errors,
5xxandrate_limitedare retried with backoff, honouringRetry-After. Items stay queued while the server is down. - Reported: events the server rejects, and requests it refuses, go to the logger and
on_errorwith the reason. - Bad key: after a
401, sending stops until the app restarts, and one error is logged. - Quota: after
quota_exceeded, events are dropped for an hour before the next attempt. - Forking servers: a forked process (Puma workers, job runners) starts its own queue and thread on first use.
- Exit: the queue is flushed when the process exits, for up to 5 seconds.
AppsPatrol.flush(timeout: 5) # send what is queued now; true when the queue is empty afterwards
AppsPatrol.shutdown # flush and stop the thread
Call AppsPatrol.flush at the end of a short script or a rake task that tracks events.
Testing your app
# spec/rails_helper.rb
require "apps_patrol/rspec"
RSpec.configure { |config| config.before { AppsPatrol::Testing.fake! } }
# in a spec
expect { post bulk_update_products_path, params: { ids: [1, 2] } }
.to have_tracked("feature_used").with(feature: "bulk_edit").for_shop("example.myshopify.com")
AppsPatrol::Testing.events # every tracked event
AppsPatrol::Testing.shops # every identify call
With the fake in place nothing is sent. Without RSpec, require "apps_patrol/testing" gives the same recorder without the matcher.
Not in this version
Delivery through Active Job, an install generator and request compression are not included.