{"name":"install-snagr","title":"Install Snagr in a codebase","description":"Install the Snagr SDK, track start/stop events (checkout, signup, onboarding, trial), and create recovery flows so Snagr follows up with people who don't finish.","when":"The user asks to set up Snagr, add abandoned checkout / onboarding recovery, or install the Snagr SDK.","steps":[],"endpoints":["/api/mcp","/api/v1/batch","/sdk.js"],"markdown":"---\nname: install-snagr\ndescription: \"Install Snagr using its browser script and HTTP API, verify identity and events, and draft a recovery flow through MCP.\"\n---\n\n# Install Snagr\n\nSnagr follows up when a start event arrives and the finish event does not. Read https://www.snagr.sh/sdk and https://www.snagr.sh/agents first. The npm package is not publicly published yet: use the hosted browser script and server HTTP API below.\n\n## 1. Get access\n\nThe merchant signs up at https://www.snagr.sh/sign-up?setup=agent and gets keys at /developers. The publishable key belongs in the browser. SNAGR_SECRET_KEY belongs only in the server environment; never put it in client code, public environment variables, prompts committed to the repository, or logs.\n\nFor Claude Code: claude mcp add --transport http snagr https://www.snagr.sh/api/mcp --header \"Authorization: Bearer $SNAGR_SECRET_KEY\". Other clients use the same HTTP endpoint and bearer header. Without authentication only public documentation tools are available. Team tools require Pro or eligible Free access before the first recovered payment.\n\n## 2. Discover the integration points\n\nRead the codebase. Locate authenticated identity, checkout creation, signup completion, trial creation and verified payment webhooks. Choose the real start and finish events and a return URL in the merchant's app that can resume the action. Do not send an expired checkout URL. Explain the proposed file changes and follow the merchant's existing authorization; do not ask again if they already authorized installation.\n\nSuggested pairs: checkout_started → purchase_completed; signed_up → onboarding_completed; trial_started → purchase_completed. onboarding_completed records activation, not recovered revenue. Use a separate paid-conversion flow when needed.\n\n## 3. Install and identify\n\nPlace the queue stub and script in the application's HTML layout before event calls. In an SPA load the script once. Keep the publishable key in the app's browser configuration. Do not invent keys.\n\n```html\n<!-- Put this before your app's event handlers -->\n<script>\n  window.snagr = window.snagr || { _q: [] };\n  [\"track\", \"identify\", \"reset\", \"onState\"].forEach(function (method) {\n    window.snagr[method] = function () {\n      window.snagr._q.push([method, arguments]);\n    };\n  });\n</script>\n<script src=\"https://www.snagr.sh/sdk.js\"\n  data-key=\"YOUR_PUBLISHABLE_KEY\" defer></script>\n```\n\nSign an authenticated user's normalized email on the server with the secret key and pass the hash, not the key, to the browser. Leave unverified-email sending disabled.\n\n```js\n// On your server, after authenticating the user:\nimport { createHmac } from \"node:crypto\";\nconst emailHash = createHmac(\"sha256\", process.env.SNAGR_SECRET_KEY)\n  .update(user.email.trim().toLowerCase()).digest(\"hex\");\n\n// Pass emailHash to your authenticated browser session:\nwindow.snagr.identify({ email: user.email, userId: user.id, emailHash });\nwindow.snagr.track(\"checkout_started\", { url: resumeUrl });\n```\n\nFor server-only installations, send start events using the server API and the user's email; omit browser identity. On-site nudges require the browser script and identified people.\n\n## 4. Confirm completion from the server\n\nAfter verifying the payment-provider webhook and confirming that the payment is paid, send the finish event. A completed Stripe Checkout Session can still be unpaid for delayed methods. Use the appropriate successful-payment event. Use the same messageId on retries, and choose IDs that do not collide across event types. Revenue below assumes a two-decimal USD order.\n\n```js\n// In your server, after verifying the payment webhook:\nconst response = await fetch(\"https://www.snagr.sh/api/v1/batch\", {\n  method: \"POST\",\n  headers: {\n    Authorization: \"Bearer \" + process.env.SNAGR_SECRET_KEY,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({ batch: [{\n    type: \"track\", email: customer.email,\n    event: \"purchase_completed\", messageId: order.id,\n    properties: { revenue: order.amount / 100, currency: \"USD\" },\n  }] }),\n});\nconst result = await response.json();\nif (!response.ok || !result.results?.every((item) => item.ok)) {\n  throw new Error(\"Snagr event delivery failed\");\n}\n```\n\nHandle HTTP failures and inspect each batch result. Retry failed delivery using the same messageId. Do not block successful checkout fulfillment indefinitely on an analytics call; use the app's existing background queue when available.\n\n## 5. Draft and verify the flow\n\nUse list_recent_events to verify delivery. create_flow accepts name, trigger_event, stop_event, steps and active. Always set active:false while drafting. Email steps use delay_minutes and markdown; nudges use type:nudge and a nudge object with title, body, cta_text, cta_url and style. Flags and signed webhook steps are also available. All delays are measured from the trigger.\n\nInspect the merchant's own events and get_person for a test address they own. Never send a test to a customer. Do not invent recovered revenue. Show the code changes, approved copy and test results. Enable the flow with update_flow only once the merchant has reviewed and authorized sending.\n\n## Checks before finishing\n\nConfirm that secret keys stay server-side; email identity is verified; start and stop event names match the flow; the return URL is usable; failed batch results are handled; retries are idempotent; and an onboarding finish event does not count as a payment. Summarize the exact files changed and any missing credentials or deployment work.\n","url":"https://www.snagr.sh/.well-known/agent-skills/install-snagr/SKILL.md"}