Event discovery and tracking coverage

What this adds to event ingestion

Shopify lifecycle and collections provide install, subscription and collection facts. Optional product milestones come from your app’s own tracking code. HeyCrust does not discover arbitrary UI steps automatically. Follow backend events for safe emission, immutable retries, acknowledgement and redaction handling.

Inspect actual stored observations

Use Merchants → Custom events, list_custom_event_types and list_custom_events with one owned app and explicit UTC timestamps. Compare full event counts with distinct names; page through returned records with the unchanged cursor scope. Occurrence time is separate from receipt time. Exact app-bound merchant identity may remain unresolved even when an event is stored.

API and pixel are transport channels. Pixel is browser reported; API defaults to app reported when no evidence-origin claim is supplied, but evidence_origin: storefront_browser or browser_reported remains browser reported. Other claims are unknown. These labels do not independently verify the underlying action. Never relabel browser evidence as backend success.

Define safe milestone metadata

Owners create named definitions in Custom events. A definition has a label (1–100 characters), description (up to 500), expected origin and up to 20 allowed scalar property keys. Names use the existing event-name syntax and are immutable; revisions retain the earlier version. A funnel pins each custom requirement to a definition ID and revision.

Inspection returns only the chosen non-sensitive properties. Sensitive key patterns, email/URL/credential-like string values, arrays, nested objects and unknown keys are omitted. This is an inspection boundary: it does not sanitize the ingestion endpoint or justify sending secrets. Send minimal properties at the source. Event exports omit raw properties and external event IDs.

Declare release coverage

Add explicit owner declarations for the definition revision and reported origin, with deployed-from UTC time, optional through time and release label. Keep gaps and release boundaries accurate. Owners can select historical revisions and correct or close an existing declaration with an optimistic content revision; the earlier open interval is replaced, so it cannot cover a later gap. An ongoing declaration ends at query time during evaluation. Declarations neither deploy your app nor confirm that every merchant is instrumented.

Funnels evaluate declared milestone intervals together with source history/checkpoints, exact identity and episode boundaries. A stored positive observation can show progress while missing coverage leaves absence unknown. Source coverage is evaluated per episode; a historical mature window is not judged against a later entry’s window. Reinstall and uninstall boundaries prevent combining unrelated installations.

Validate and read through MCP

validate_activation_funnel validates a proposed definition and owned references without writing. It is not an authoring API. Create the saved version in Activation, discover it with list_activation_funnels, then read it with get_activation_funnel. Set includeMerchants: true for stage/state drills and inspect an exact shop with get_activation_journey.

Use explicit app, dates and version for reproducible comparisons. Reads create no tracking event, reconciliation task, provider setup or automation. Do not send synthetic production events simply to make a test pass. Verify real naturally occurring receipts and downstream delivery separately after an authorized release.

Unavailable reads

A PostgreSQL query timeout is diagnosed as query_timeout across discovery, validation and activation reads. An early timeout before owned definition metadata is available returns a minimal unavailable result with no totals; owner HTTP reads use 503 and MCP returns the safe unavailable status/reasons. The native page offers retry. Scope/validation failures retain their own handling. Calculation work has a separate five-second deadline (calculation_timeout), and episode lists are paginated.