Skill: leo-paz/outlit-sdk (version 1.0.1)

--- name: outlit-sdk description: Use when integrating Outlit tracking into web, server, native, or desktop apps; adding SDK event tracking, identity, consent, activation, billing, visitor tracking, customerId attribution, or troubleshooting @outlit/browser, @outlit/node, or the Rust outlit crate. metadata: openclaw: homepage: "https://outlit.ai" emoji: "🔦" --- # Outlit SDK Integration Decision-tree guide for adding product and website tracking to the Outlit customer context graph. Detect first, ask only when needed, keep changes small, and prefer official docs for framework-specific code. This skill has no runtime credential requirement of its own. Environment variable names in this guide, such as `NEXT_PUBLIC_OUTLIT_KEY` or `OUTLIT_KEY`, are examples for the target application being instrumented. ## Branching Check Before anything else, check whether Outlit is already installed: 1. Look for `@outlit/browser`, `@outlit/node`, `outlit` in `Cargo.toml`, `https://cdn.outlit.ai`, or existing `outlit.init(...)` / `new Outlit(...)` calls. 2. If not installed, go to [Phase 1: Quick Connect](#phase-1-quick-connect). 3. If installed, go to [Already Installed](#already-installed). ## Already Installed Ask what they need help with, then run detection before changing code: - Add event tracking -> [Decision 6: Event Tracking](#decision-6-event-tracking) - Add/change auth identity -> [Decision 2: Identity](#decision-2-identity) - Add consent management -> [Decision 1: Consent](#decision-1-consent) - Add server/native tracking -> [Decision 7: Server and Native Tracking](#decision-7-server-and-native-tracking) - Add activation tracking -> [Decision 4: Activation](#decision-4-activation) - Add billing/Stripe integration -> [Decision 5: Billing](#decision-5-billing) - Migrate from other analytics -> [Decision 3: Existing Analytics](#decision-3-existing-analytics) - Debug/troubleshoot -> [Troubleshooting](#troubleshooting) ## Current API Guardrails These points prevent the most common stale integrations: - All current ingest SDKs use `publicKey` values that start with `pk_`. Do not use `privateKey`, `OUTLIT_PRIVATE_KEY`, `visitorId`, or `event` for `@outlit/node` examples. - Node server events use `new Outlit({ publicKey })` and `track({ eventName, email | userId | fingerprint | customerId, properties })`. - Browser anonymous events are valid without identity. Server `track()` requires at least one of `email`, `userId`, `fingerprint`, or `customerId`. - Server `identify()` requires `email` or `userId`. `customerId` is optional account/workspace attribution, not a user identity by itself. - Use `customerId` for your system-owned account/workspace/customer ID. The TypeScript SDK no longer uses `customerDomain`; do not add it. - Browser `setUser()` can be called before tracking is enabled and will be applied after consent. Browser `identify()` requires tracking to already be enabled. - `user.activate()` is the only journey stage new integrations should send manually. `user.engaged()` and `user.inactive()` are deprecated; Outlit derives engagement and inactivity from tracked product activity. - Billing is account-level. In TypeScript billing methods, prefer `customerId`; `stripeCustomerId` is compatibility-only. In Rust billing methods still start with a domain and can add `.customer_id(...)`. - Event names should be `snake_case`. SDK events get UUIDv7 event IDs automatically; do not generate event IDs manually. ## Phase 1: Quick Connect Goal: get data flowing quickly so the user can see Outlit connection/activity without making product-strategy decisions. ### Step 1: Detect Framework and Package Manager Check: | Signal | How to detect | |--------|---------------| | Framework | `package.json` deps: `next`, `react`, `vue`, `nuxt`, `svelte`, `@sveltejs/kit`, `@angular/core`, `astro`, `express`, `fastify`, `electron`, `react-native`; `Cargo.toml` deps: `tauri`, `outlit` | | Package manager | `bun.lockb`, `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json` | | Current Outlit | `@outlit/browser`, `@outlit/node`, CDN script, Rust crate, `outlit.init`, `OutlitProvider`, `OutlitPlugin`, `new Outlit` | ### Step 2: Choose SDK | App surface | Use | |-------------|-----| | Browser app: React, Next.js, Vue, Nuxt, SvelteKit, Angular, Astro, vanilla, script tag | `@outlit/browser` | | Node backend: API routes, server actions, Express, Fastify, jobs, webhooks | `@outlit/node` | | Native JS without browser storage: React Native, CLI, desktop main process | `@outlit/node` with a stable `fingerprint` | | Rust backend, CLI, or Tauri backend | Rust crate `outlit` | | Electron renderer or webview | `@outlit/browser`; use `@outlit/node` in main process only if tracking native/background events | Install with the detected manager. Prefer `bun add` when the repo is a Bun workspace. ### Step 3: Add Public Key Ask for the Outlit public key from **Outlit dashboard -> Settings -> Website Tracking** or onboarding. Use the framework's public env convention: | Framework | Env var | |-----------|---------| | Next.js | `NEXT_PUBLIC_OUTLIT_KEY` | | Vite / Vue / React+Vite / Svelte | `VITE_OUTLIT_KEY` | | SvelteKit | `PUBLIC_OUTLIT_KEY` | | Nuxt | `NUXT_PUBLIC_OUTLIT_KEY` | | Astro | `PUBLIC_OUTLIT_KEY` | | Create React App | `REACT_APP_OUTLIT_KEY` | | Angular | `environment.ts` or equivalent | | Server/native | `OUTLIT_KEY` or `OUTLIT_PUBLIC_KEY` | ### Step 4: Minimal Setup Fetch the framework doc from the [Doc URL Map](#doc-url-map) and implement only startup initialization: - React/Next: prefer `OutlitProvider` from `@outlit/browser/react` in a client boundary. - Vue/Nuxt: use `OutlitPlugin` from `@outlit/browser/vue`. - Plain browser/script: use `@outlit/browser` or CDN script. - Server/native: create one `Outlit` instance where the process can reuse it. Do not add custom events, activation, billing, auth, or consent until basic tracking is working unless the user asked for a full integration immediately. ### Step 5: Verify Connection Verify with one or more: - DevTools Network has `https://app.outlit.ai/api/i/v1/<publicKey>/events` returning success. - Browser console has no `[Outlit]` warnings. - Server code calls `await outlit.flush()` or `await outlit.shutdown()` before process/serverless exit. - Outlit onboarding/dashboard shows recent activity or connected tracking. Then ask whether to continue with the full integration. ## Phase 2: Full Integration Run detection and present what you found before changing behavior: | Signal | How to detect | |--------|---------------| | Auth provider | `@clerk/*`, `next-auth`, `@auth/core`, `@supabase/*`, `@auth0/*`, `firebase`, custom session/auth files | | Account model | `organization`, `workspace`, `team`, `account`, `tenant`, `customerId`, Stripe customer mapping | | Billing provider | `stripe`, `@stripe/stripe-js`, `paddle`, `chargebee`, webhook routes | | Existing analytics | `posthog-js`, `@posthog/node`, Amplitude, Mixpanel, Segment, analytics wrappers | | Consent | Cookiebot, OneTrust, cookie banner components, CMP callbacks | | Native/device | Tauri, Electron main process, React Native, CLI, mobile storage | | Activation | first workspace/project/resource, first successful integration, invite sent, report generated, first meaningful feature success | | Calendar embeds | Cal.com or Calendly embed code | ## Decision 1: Consent | Detection | Recommendation | |-----------|----------------| | Existing CMP/cookie banner | Initialize with `autoTrack: false`; call `enableTracking()` from the CMP accept callback and `disableTracking()` on revoke/decline | | EU/privacy signals but no CMP | Use `autoTrack: false` and tell the user they need a consent decision; do not build a CMP unless asked | | No consent requirement found | Use default `autoTrack: true` | Explain the tradeoff: `autoTrack: true` creates browser visitor storage immediately. `autoTrack: false` waits until `enableTracking()` is called. If identity is known before consent, use the React `user` prop or `setUser()` so identity is queued and applied after tracking starts. Do not call browser `identify()` before tracking is enabled. ## Decision 2: Identity Use the strongest identifiers available: - `email`: primary person identifier. - `userId`: the app/auth-provider user or contact ID. - `customerId`: the app's account/workspace/customer/team ID. - `customerTraits`: account/workspace metadata such as plan or seats. - `traits`: user/contact metadata such as name or role. - `fingerprint`: stable device/install ID for native or non-browser tracking. Recommendations: | Context | Pattern | |---------|---------| | React/Next | Pass `user={{ email, userId, customerId, traits, customerTraits }}` to `OutlitProvider` once auth resolves | | Vue/Nuxt | Use `useOutlitUser(refOrComputedUser)` or plugin `setUser()` | | SPA without framework helpers | Call `setUser({ email, userId, customerId })` after auth, and `clearUser()` on logout | | Script tag | Call `window.outlit.setUser(...)` after auth, or `identify(...)` after tracking is enabled | | Server Node | Call `identify({ email, userId, customerId })` for user/profile updates; call `track({ customerId, eventName })` for account-scoped events | | Native/device | Track with a persistent `fingerprint`; later call `identify({ email, fingerprint })` or Rust `.fingerprint(...)` to link history | Critical distinction: browser identify/setUser links anonymous visitor history. Server identify attributes server-side identity and can link fingerprints/customer IDs, but it does not link browser visitor cookies unless the browser also identifies. ## Decision 3: Existing Analytics | Detection | Recommendation | |-----------|----------------| | Existing analytics wrapper | Add Outlit to the wrapper | | Direct analytics calls scattered across files | Count them and ask whether to add Outlit alongside existing calls or introduce a wrapper | | PostHog connected as data source | Do not duplicate every PostHog event by default; use SDK for missing product/website/customer identity gaps | | No analytics | Add Outlit directly | Keep event names `snake_case` and avoid reorganizing unrelated analytics code. ## Decision 4: Activation Activation means a user reached the product's meaningful value moment. It is not automatically "completed onboarding" unless onboarding itself delivers value. 1. Scan for first-value actions: first project/resource created, first integration connected, first report/export generated, first invite, first successful core workflow. 2. Suggest the strongest candidate and ask for confirmation if ambiguous. 3. Call `user.activate()` only after the action is confirmed complete, usually after the backend succeeds. 4. Ensure the user is identified first. Browser SDK queues up to 10 activation events until identity is set, but the cleaner integration is to set identity before activation. 5. Do not call `user.engaged()` or `user.inactive()` in new integrations. ## Decision 5: Billing Billing is account-level context, separate from contact journey stages. | Detection | Recommendation | |-----------|----------------| | Stripe connected in Outlit | Let the Stripe integration handle trialing/paid/churned | | Stripe in app but not connected | Recommend connecting Stripe in Outlit; only add manual SDK calls if they need custom logic | | Other/custom billing | Add billing calls in existing webhook/job handlers | | No billing | Skip | TypeScript: ```ts outlit.customer.paid({ customerId: "cust_123", properties: { plan: "pro" }, }) ``` Rust currently differs: ```rust client.customer() .paid("acme.com") .customer_id("cust_123") .send() .await?; ``` Always flush server/native queues before the handler exits. ## Decision 6: Event Tracking Browser SDK defaults already capture: - pageviews, including SPA navigation - form submissions with sensitive fields removed - auto-identify from email/name form fields - engagement time and sessions - Cal.com/Calendly booking events, without attendee email/name from client-side embeds Add custom `track()` calls only for meaningful product actions that are not covered by automatic capture or connected integrations. Use properties for useful context, not PII or secrets. Calendar embed limitation: Cal.com and Calendly client events do not expose attendee email/name. Use provider webhooks plus server `identify()` when booked-meeting identity matters. Hash-routed SPAs, `file://` routes, and Electron-style hash paths are handled by the core path extractor; do not add custom path parsing unless the app has a special router. ## Decision 7: Server and Native Tracking Use server/native tracking for backend-confirmed product activity, billing, background jobs, native apps, CLIs, and device-based activity. Node example: ```ts import { Outlit } from "@outlit/node" const outlit = new Outlit({ publicKey: process.env.OUTLIT_KEY! }) outlit.track({ customerId: "cust_123", eventName: "workspace_synced", properties: { provider: "github" }, }) await outlit.flush() ``` Use `fingerprint` for native/desktop/mobile activity before login: ```ts outlit.track({ fingerprint: deviceId, eventName: "app_opened", }) outlit.identify({ email: user.email, fingerprint: deviceId, }) ``` Serverless rule: `await outlit.flush()` before returning. Long-lived process rule: reuse one client and call `shutdown()` on graceful shutdown. ## Doc URL Map Fetch docs as needed. Prefer docs over hardcoding long framework patterns, but apply the API guardrails above if examples conflict. | Topic | URL | |-------|-----| | Quickstart | `https://docs.outlit.ai/tracking/quickstart` | | How tracking works | `https://docs.outlit.ai/tracking/how-it-works` | | Customer context graph | `https://docs.outlit.ai/concepts/customer-context-graph` | | Website visitors | `https://docs.outlit.ai/concepts/website-visitors` | | Identity resolution | `https://docs.outlit.ai/concepts/identity-resolution` | | Customer journey | `https://docs.outlit.ai/concepts/customer-journey` | | NPM/browser package | `https://docs.outlit.ai/tracking/browser/npm` | | React | `https://docs.outlit.ai/tracking/browser/react` | | Next.js | `https://docs.outlit.ai/tracking/browser/nextjs` | | Vue 3 | `https://docs.outlit.ai/tracking/browser/vue` | | Nuxt | `https://docs.outlit.ai/tracking/browser/nuxt` | | SvelteKit | `https://docs.outlit.ai/tracking/browser/sveltekit` | | Angular | `https://docs.outlit.ai/tracking/browser/angular` | | Astro | `https://docs.outlit.ai/tracking/browser/astro` | | Script tag | `https://docs.outlit.ai/tracking/browser/script` | | Calendar embeds | `https://docs.outlit.ai/tracking/browser/calendar-embeds` | | Node.js | `https://docs.outlit.ai/tracking/server/nodejs` | | Rust / Tauri | `https://docs.outlit.ai/tracking/server/rust` | | Ingest API | `https://docs.outlit.ai/api-reference/ingest` | | Full docs index | `https://docs.outlit.ai/llms.txt` | ## Troubleshooting ### No browser events 1. Confirm the public env var prefix is correct and exposed to the client bundle. 2. Confirm provider/init runs once at app startup and wraps the app. 3. If `autoTrack: false`, call `enableTracking()` after consent. 4. Check Network for `/api/i/v1/<publicKey>/events`. 5. Check console warnings such as tracking not enabled, already initialized, or multiple instances. ### Events not linked to users - Prefer `OutlitProvider user`, `useOutlitUser`, or `setUser()` for auth state. - Send both `email` and `userId` when available. - Include `customerId` for account/workspace-scoped products. - Browser identity links visitor history; server identity does not replace browser identity. - For native/device history, reuse the same persistent `fingerprint` before and after login. ### Server events missing - Use `publicKey`, not `privateKey`. - Use `eventName`, not `event`. - Provide at least one of `email`, `userId`, `fingerprint`, or `customerId` to `track()`. - `identify()` needs `email` or `userId`. - Always `await outlit.flush()` before serverless handlers return. - Non-retryable ingest errors stop automatic retries until restart; fix credentials/config instead of waiting. ### Activation missing or delayed - Call activation after identity is set. - In browsers, `user.activate()` can queue until `setUser()`/`identify()` provides identity, but the queue is bounded. - Do not use deprecated `engaged`/`inactive` calls; send product activity with `track()`. ## Key Principles - Minimal changes: instrument the existing app shape. - Detect first, ask second. - Use `customerId` for account/workspace context. - Use `setUser`/provider user for auth lifecycle. - Use `track()` for product activity; use `user.activate()` only for the activation milestone. - Flush server/native queues before exit. - Keep events `snake_case`. ## Installation Install this skill through the Outlit CLI when possible: ```sh outlit setup skills ``` Or with the Skills CLI: ```sh npx -y skills add https://github.com/OutlitAI/outlit-agent-skills --skill outlit-sdk -g ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)