apps.patrol docs

Events

Which events to send, the standard names and what Apps Patrol does with them.

Apps Patrol already knows who installed, who pays and who left, from your Partner account. Events add what merchants do inside your app. You decide what to send: any event name is accepted.

Standard events

These names are a convention. Using them is optional, but they are the ones Apps Patrol gives meaning to, and both client libraries have a helper for each.

EventPropertiesSend it when
app_openednoneA shop opens your app. Sent automatically by the libraries, at most once per shop per day.
onboarding_startedanyA merchant begins first-run setup.
onboarding_completedanySetup is finished and the app is usable.
feature_usedfeatureA merchant uses a core feature.
plan_viewedanyThe pricing or plans page is opened.
upgrade_clickedany, for example planA merchant presses an upgrade button.
limit_reachedlimitA shop hits a limit of its plan.
error_showncodeA merchant sees an error.

What Apps Patrol does with them today

  • The Events page shows counts per event name, the most recent events, and the month's usage against your plan.
  • Daily active shops are counted from app_opened, onboarding_completed and feature_used.

Activation, feature adoption and inactive paying shops are planned views. They will read the standard names, so events you send now will count when those views arrive.

The automatic app_opened

  • Ruby: under Rails, sent after a successful HTML page request in any controller that has a Shopify session (current_shopify_domain). Switch it off with config.auto_app_opened = false.
  • Node: sent by identifyAfterAuth and patrolMiddleware, or call patrol.appOpened(shop) in your root loader.

The event ID is built from the shop and the date (app_opened:<shop>:<YYYY-MM-DD>, UTC), so one event per shop per day is stored however many servers send it.

Your own events

Send anything else that shows whether a merchant gets value, for example reservation_created or auction.started. Names may use lowercase letters, digits and _ . : -. See the Events API for the limits on names and properties.

What not to send

  • Nothing about a merchant's customers: no names, emails, addresses or order contents. Apps Patrol is built on holding no end-customer data.
  • Not every click or page view. Each plan has a monthly event allowance, and a handful of meaningful events per shop is more useful than a stream.
  • No secrets in properties.