outlit-sdk

集成 Outlit SDK 以获取代理的客户背景。当用户需要将 Outlit 添加到任何 Web 框架（React、Next.js、Vue、Nuxt、Svelte、Angular、Astro）、服务器运行时（Node.js、Express、Fastify）、桌面应用程序（Tauri、Electron），或者需要 Outlit 事件跟踪、用户身份、同意管理、分析迁移、激活事件、计费生命周期或对现有 Outlit 安装进行故障排除方面的帮助时触发。

## 概述（中文）

集成 Outlit SDK 以获取代理的客户背景。当用户需要将 Outlit 添加到任何 Web 框架（React、Next.js、Vue、Nuxt、Svelte、Angular、Astro）、服务器运行时（Node.js、Express、Fastify）、桌面应用程序（Tauri、Electron），或者需要 Outlit 事件跟踪、用户身份、同意管理、分析迁移、激活事件、计费生命周期或对现有 Outlit 安装进行故障排除方面的帮助时触发。

## 原文

# Outlit SDK Integration

Decision-tree-driven guide for integrating Outlit customer journey tracking. Detects what it can from the codebase, asks only what it must, and links to official docs for implementation details.

## Branching Check

Before anything else, check if Outlit is already installed:

1. Look for `@outlit/browser`, `@outlit/node`, or `outlit` (Rust crate) in `package.json` or `Cargo.toml`
2. If **not installed** -> go to [Phase 1: Quick Connect](#phase-1-quick-connect)
3. If **already installed** -> go to [Already Installed](#already-installed)

## Already Installed

Ask the user what they need help with:

- **Add event tracking** -> Run detection, then go to [Decision 7: Event Tracking](#decision-7-event-tracking). Fetch the relevant framework doc from the [Doc URL Map](#doc-url-map) for implementation patterns.
- **Add/change auth integration** -> Run detection, then go to [Decision 3: Auth & Identity](#decision-3-auth--identity). Fetch the framework doc and [identity resolution](https://docs.outlit.ai/concepts/identity-resolution) doc.
- **Add consent management** -> Go to [Decision 2: Consent Stance](#decision-2-consent-stance). Fetch the framework doc's consent section.
- **Add server-side tracking** -> Go to [Decision 1: App Type & SDK](#decision-1-app-type--sdk-package) for the server package, then fetch the [Node.js](https://docs.outlit.ai/tracking/server/nodejs) or [Rust](https://docs.outlit.ai/tracking/server/rust) doc.
- **Add billing/Stripe integration** -> Go to [Decision 6: Billing Integration](#decision-6-billing-integration). Fetch the [customer journey](https://docs.outlit.ai/concepts/customer-journey) doc.
- **Add activation tracking** -> Go to [Decision 5: Activation Event](#decision-5-activation-event). Fetch the [customer journey](https://docs.outlit.ai/concepts/customer-journey) doc.
- **Migrate from other analytics** -> Run detection, then go to [Decision 4: Existing Analytics](#decision-4-existing-analytics-strategy).
- **Debug/troubleshoot** -> Go to [Troubleshooting](#troubleshooting).

## Phase 1: Quick Connect

Goal: get events flowing in ~2 minutes so the user sees "Connected" on their Outlit onboarding screen. Zero user decisions required.

### Step 1: Detect Framework & Package Manager

Use glob/grep to check:

- **Framework:** Check `package.json` dependencies for `next`, `vue`, `nuxt`, `react`, `svelte`, `@sveltejs/kit`, `@angular/core`, `astro`, `express`, `fastify`. Check for `Cargo.toml` with `tauri` or `outlit`.
- **Package manager:** Check for `bun.lockb` (bun), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `package-lock.json` (npm). Use the first match found.

### Step 2: Install SDK

Based on detected framework:

- Browser app (React, Next.js, Vue, Nuxt, Svelte, Angular, Astro) -> `@outlit/browser`
- Server app (Express, Fastify, Node.js) -> `@outlit/node`
- Tauri -> `outlit` Rust crate via `cargo add outlit`
- Electron -> `@outlit/browser`

Install using the detected package manager.

### Step 3: Add Public Key

Ask the user for their Outlit public key. They get it from **Outlit dashboard -> Settings -> Website Tracking** or from the onboarding screen.

Add to environment variables with the correct framework prefix:

| Framework | Env var |
|-----------|---------|
| Next.js | `NEXT_PUBLIC_OUTLIT_KEY` |
| Vite (Vue, Svelte, React+Vite) | `VITE_OUTLIT_KEY` |
| Create React App | `REACT_APP_OUTLIT_KEY` |
| Nuxt | `NUXT_PUBLIC_OUTLIT_KEY` |
| Angular | Add to `environment.ts` |
| Astro | `PUBLIC_OUTLIT_KEY` |
| Server apps | `OUTLIT_KEY` |

### Step 4: Minimal Setup

Fetch the framework-specific doc from the [Doc URL Map](#doc-url-map) and implement only the minimal setup — provider/init with just the `publicKey`, no auth, no consent, no custom events.

For React-based frameworks this means wrapping the app with `OutlitProvider`. For Vue it means installing the `OutlitPlugin`. For server apps it means creating an Outlit instance.

### Step 5: Verify Connection

Tell the user to:

1. Run their dev server
2. Open the app in a browser
3. Check the Outlit onboarding screen for the **"Connected"** badge
4. Or check DevTools -> Network for requests to `app.outlit.ai/api/i/v1/...` returning 200

Once connected, ask: **"Events are flowing. Ready to set up the full integration?"**

If yes -> continue to Phase 2. If no -> they can come back later (the skill will detect the existing install).

## Phase 2: Full Integration

Run the full detection first, then walk through each decision.

### Full Detection

Use grep/glob to detect all of the following before starting the decision tree:

| Signal | How to detect |
|--------|--------------|
| Auth provider | Deps: `@clerk/nextjs`, `@clerk/clerk-react`, `next-auth`, `@auth/core`, `@supabase/auth-helpers-nextjs`, `@supabase/ssr`, `@auth0/auth0-react`, `@auth0/nextjs-auth0`, `firebase`, `@firebase/auth` |
| Billing provider | Deps: `stripe`, `@stripe/stripe-js`, `@paddle/paddle-js`, `chargebee` |
| Existing analytics | Deps: `posthog-js`, `@posthog/node`, `@amplitude/analytics-browser`, `@amplitude/analytics-node`, `mixpanel-browser`, `@segment/analytics-next`, `@segment/analytics-node` |
| Analytics abstraction | Grep for files named `analytics.ts`, `analytics.js`, `tracking.ts`, `tracking.js` in `lib/`, `utils/`, `helpers/`, `services/` that import 2+ analytics libraries |
| EU/consent signals | Deps: `cookiebot`, `@onetrust/*`, `cookie-consent`, or grep for existing consent/cookie banner components |
| App type | Deps: `@tauri-apps/api`, `electron`, `react-native` |
| Activation patterns | Grep for onboarding routes/components, "first" resource creation handlers, invite flows |

Present a summary of what was detected to the user before proceeding.

### Decision 1: App Type & SDK Package

Auto-resolved from Phase 1 detection. If hybrid (e.g., Next.js with API routes that need server tracking), install both `@outlit/browser` and `@outlit/node`.

- Electron -> `@outlit/browser`
- Tauri -> `outlit` Rust crate
- React Native -> `@outlit/browser` (uses fingerprint instead of cookies)

### Decision 2: Consent Stance

| Detection | Recommendation |
|-----------|---------------|
| Existing CMP/cookie banner library | `autoTrack: false`, integrate with their existing CMP's consent callback to call `enableTracking()` |
| EU signals but no CMP | `autoTrack: false`, mention they need a consent solution but don't build one unless asked |
| No EU signals | `autoTrack: true` — simpler, uses cookies immediately |

**Always explain the tradeoff:** `autoTrack: true` starts tracking with cookies immediately. `autoTrack: false` waits until `enableTracking()` is called after user consent.

Fetch the relevant framework doc for consent implementation patterns.

### Decision 3: Auth & Identity

| Detection | Recommendation |
|-----------|---------------|
| React/Vue with OutlitProvider/OutlitPlugin | Pass `user` prop with `{ email, userId }` after auth resolves. No manual `identify()` needed. |
| Vanilla JS / script tag | Call `outlit.identify({ email, userId })` client-side right after auth completes |
| Server-only (Node/Rust) | Call `outlit.identify()` server-side for event attribution |

**Critical:** Client-side `identify()` (or the `user` prop) links the anonymous cookie/visitorId to a real person. This must happen after the auth flow completes. Server-side `identify()` is for attributing server events to a known user, but doesn't link browsing history.

If an auth provider was detected, fetch the framework doc and the [identity resolution](https://docs.outlit.ai/concepts/identity-resolution) doc for the specific auth provider pattern.

### Decision 4: Existing Analytics Strategy

| Detection | Recommendation |
|-----------|---------------|