Instrument your app with Claude Code or Cursor

Instrument your app with Claude Code or Cursor

Aim for a first integration review in 10 minutes. This is a setup target, not a measured completion promise. Deployment, Shopify history import and natural merchant activity can take longer. See the evidence status below.

The guided setup has three to five steps: your app, account (new users only), Shopify connection, optional activity, and verification. Saved setup resumes from Apps → Continue setup. Add another app without creating another account.

1. Connect the correct app

Start with your Shopify Partner app ID. Create or sign in to your Crust account when prompted, then enter the Partner organization and API credentials. Existing owners can reuse their workspace connection. Verify the exact app ID before giving a coding agent repository access. Read credential boundaries.

2. Review the event plan with your coding agent

Connect MCP in Claude Code or Cursor. Ask for get_instrumentation_plan for your owned Crust app UUID. Review the five to ten proposed setup, value, feature and error observations. Edit their business meaning and safe property allowlist. Registration requires explicit confirmation and pins definitions and a default funnel; it does not establish deployment coverage or send messages.

Use generate_tracking_code with the reviewed plan. Every reviewed event has a concrete trackingEvents[name].prepare and .record helper. Keep Shopify mirroring off unless you intentionally configure it. Monitoring handles must never be pricing meters.

3. Install the backend package

Download the Node package with Ruby/PHP bindings and extract crust-tracking/ next to your server module. This is a downloadable package, not a published npm package. Use Node 22.13+ or 24+ and persistent local disk for its bounded queue. A host outbox can instead use the exported delivery transport and reporting consumers.

Save the generated example as crust-events.server.mjs. Set the private key and queue directory on your app backend; the public Crust event endpoint is https://heycrust.com/api/events. Never put these credentials in the browser.

import { trackingEvents } from './crust-events.server.mjs';

// Your existing authenticated server action supplies verifiedShop.
// operation has a persistent logical ID and its original UTC occurrence time.
const prepared = trackingEvents.setup_completed.prepare(verifiedShop, operation, {});
// Atomically persist ALL of prepared with the real business write.
// After commit, load that exact saved event and deliver it:
await trackingEvents.setup_completed.record(persistedEvent);
// Retries reuse persistedEvent unchanged, including original shop identity.

New events use crust.portable.v1, verified permanent Shopify shop identity, immutable occurrence and logical ID, and bounded safe properties. Permanent means Shopify's stable identity format, not permission to retain identity after erasure. Keep your host lifecycle and trusted deletion fence around delivery; do not recreate an event from a new timestamp during retries. Inspect enqueue results, queue status and dead letters.

For an optional app widget, import createEngagementAppHandler from ./crust-tracking/engagement.mjs. The browser sends its fresh Shopify identity token only to your own authenticated backend. Keep the widget credential there and use https://heycrust.com as the Crust origin. Configuration and preview remain disabled/fictional until explicitly saved and enabled.

Ruby and PHP backends

Choose framework: "ruby" or "php" in generate_tracking_code, or the matching server framework in guided setup. The generated services run inside Ruby/Rails or PHP/Laravel backends using your existing authenticated Shopify identity and transaction lifecycle. They do not invent framework authentication APIs.

These are local process bindings to the included Node durable engine: Node 22.13+ or 24+, POSIX process spawning, and persistent local disk are required. Ruby 3.1.0 and PHP 8.4.26 were exercised with the actual extracted archive. There is no standalone native SDK or gem/Composer publication. Install the complete archive and follow its README, private JSON configuration, server environment and separate supervised worker instructions. Keep the configuration and code outside public directories. The worker uses the same app, volume and Unix user.

The generated code returns prepared: true with a safe event to store alongside your business write. After commit, record(savedEvent) waits only for durable local enqueue; it never waits for provider HTTP. Check queued: false and keep the original outbox event for retry. Missing runtime/configuration and timeouts are observable BRIDGE_UNAVAILABLE results. A timeout can occur after commit, so retry the exact original ID/time. Monitor queue status, saturation, pending targets and dead letters. An unavailable worker leaves events durably pending. Foreign process startup throughput is not covered by the earlier Node load test.

4. Verify receipts and read your results

After your authorized deployment, use verify_events for an explicit UTC window and inspect naturally occurring receipts. A Crust receipt proves server persistence, not milestone truth or Shopify Analytics display. Shopify mirroring is a separate transport observation; provider preview eligibility and event declarations are separate. Do not send synthetic production events merely to finish setup.

Open Product intelligence → Configure reports to review proposed categories from the registered plan. Only an empty unsaved configuration is prefilled; explicitly Save after review. Existing configurations and pins are preserved. No prices, attempts, deployment coverage, prediction or message permission are inferred.

Inspect Activation, Product intelligence, Merchant health, Daily actions and Release comparisons for the same selected app. Missing coverage, immature cohorts and unknown currency remain visible. Health is provisional rule-based prioritization. Draft actions need separate review and activation; email digests are opt-in.

Timing and evidence status

The 10-minute path remains a target, not a promise. Inspect the recorded Tably setup and recorded Urgency setup. These are actual internal automation runs on clean copies of the uninstrumented app baselines, applying already-reviewed changes. They use Node 22.13, an extracted package installed offline, the real MCP tool handlers, every generated helper, an actual isolated host SQL business write, and actual Crust test-database receipts. The transcript includes missing and malformed verification and the created default funnel.

The recording clock covers the executed automation, not prior development, app dependency installation, MCP client connection, credential setup or a new developer deciding where to instrument. Host authentication and provider transport are explicit fixtures. The recordings do not establish an unassisted under-15-minute setup result or three external developer sessions. No Shopify Dashboard acceptance, mature commercial gate, 95% natural-install coverage or genuine Mantle CSV validation is claimed.

In a single paired desktop browser lab observation at 1280 × 720, the optional async engagement helper was 2,274 bytes gzip; baseline/with-helper LCP was 104/48 ms, CLS 0/0, and the observed INP candidate was 24/24 ms. This small local fixture sample is not a causal performance estimate, a Shopify storefront measurement, or field Web Vitals. Read the evidence and reproduction limits.

Storage, migration and export

Shopify windows are source-specific: the historical-events reference describes a default last-30-days query, not universal deletion after 30 days. Historical billing queries, App Events monitoring and dashboard previews are separate sources; do not infer monitoring backfill from billing history. Crust can retain received history beyond a report's selected window, subject to record-specific pruning, account deletion and trusted merchant erasure. It cannot recover history it never received or promise permanent private identity storage. There are no advertised 90/180-day storage tiers.

Import & export maps CSV headers to fields, creates an immutable preview, and requires review before commit. Existing contacts are preserved; supported flows become Draft. Review records keep source labels and may remain unresolved. A genuine Mantle export remains unvalidated.

Owned exports automatically follow category pages, reconstruct large fields and include business files in a TAR archive. The manifest lists excluded protected/credential fields. Reads are live, not a frozen snapshot; concurrent changes can require a retry. The browser archive is bounded at 128 MB; select individual categories for larger workspaces. See Security, Privacy, and the DPA.

Existing unmarked integrations

Existing unmarked event payloads retain their compatibility behavior. The backend event reference labels that contract separately. Use the portable generated package for new integrations; do not mix legacy optional timestamp behavior with durable event retries.