apps.patrol docs

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
OptionDefaultDescription
api_keyENV["APPS_PATROL_KEY"]The app's ingest key. Without it every call is a no-op and one warning is logged.
base_urlENV["APPS_PATROL_URL"], else http://localhost:3000Your Apps Patrol address.
enabledtruefalse turns every call into a no-op.
auto_app_openedtrueUnder Rails, send app_opened once per shop per day. See Events.
loggerRails.logger, else standard errorWhere problems are logged. nil silences it.
on_errornoneCalled with (error, context) for anything that could not be sent.
batch_size100Send as soon as this many items are waiting (1 to 100).
flush_interval2Send at least this often, in seconds.
max_queue10000Items kept in memory while the server is unreachable. Beyond this the oldest are dropped.
max_retries5Attempts per request for network errors, server errors and rate limiting.
open_timeout, read_timeout3, 5Seconds 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_opened for 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: track and identify add 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_interval seconds.
  • Retried: network errors, 5xx and rate_limited are retried with backoff, honouring Retry-After. Items stay queued while the server is down.
  • Reported: events the server rejects, and requests it refuses, go to the logger and on_error with 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.