---
name: sophi
description: Use when integrating Sophi (agentic commerce) into a storefront or app — product feed/catalog sync, the Web Object analytics SDK, the Web SDK chat widget, and cookie-consent. Fetches the latest Sophi developer docs on demand.
---

# Sophi Integration Skill

You are an expert Sophi integration engineer. Always work from the live docs — never rely on training-data memory for Sophi-specific details, because the SDK evolves.

## Canonical Names — Use Exactly, Never Invent

Two packages, and only these:

- **`@usesophi/sophi-web-sdk`** — the chat assistant widget.
  `import { SophiWidget } from "@usesophi/sophi-web-sdk"` → `new SophiWidget()` → `await widget.init({ apiKey, container, ... })`.
- **`@usesophi/sophi-web-object`** — storefront event tracking.
  Set `window.sophi_object.config = { apiKey, ... }`; after the bundle loads, `window.SophiTracker` exposes `push(partial)`, `setConsent(granted)`, `updateUser(userId)`, and `getSession()`. Events are emitted from watched keys (`page`, `product`, `basket`, `listing`, `transaction`, `user`) on `push(...)`.

🚫 **These do NOT exist — never emit them** (they are common hallucinations):
`@sophi/sdk`, `new SophiTracker(...)`, `tracker.track('product_view', ...)` or any `.track()` method, a `store` / `storeId` option. There is no constructor and no `.track()` — send events with `SophiTracker.push({ product, page, ... })`.

If you are about to write any 🚫 item, STOP and re-read the fetched page.

## Live Doc Endpoints

| Resource | URL |
|---|---|
| Full LLM bundle (read this first) | https://docs.usesophi.com/llms-full.txt |
| Page index | https://docs.usesophi.com/llms.txt |
| Any page as Markdown | Append `.md` to the page path, e.g. https://docs.usesophi.com/docs/frontend-integration/sdk/installation.md |

## Integration Tracks

### Track 1 — Product Integration (catalog sync)

Sync your product catalog to Sophi via a structured XML feed (RSS 2.0 / Google Merchant Center compatible).

- Overview: https://docs.usesophi.com/docs/product-integration.md
- Feed specification (required fields, variant rules, common mistakes): https://docs.usesophi.com/docs/product-integration/feed-guide.md

### Track 2 — Frontend Integration (Web SDK + Web Object)

Embed the Sophi assistant chat widget and track storefront behavior.

- Overview: https://docs.usesophi.com/docs/frontend-integration.md
- **Web SDK** (chat widget):
  - Installation: https://docs.usesophi.com/docs/frontend-integration/sdk/installation.md
  - Initialization: https://docs.usesophi.com/docs/frontend-integration/sdk/initialization.md
  - Events reference: https://docs.usesophi.com/docs/frontend-integration/sdk/events.md
  - Methods: https://docs.usesophi.com/docs/frontend-integration/sdk/methods.md
  - GTM integration: https://docs.usesophi.com/docs/frontend-integration/sdk/gtm-integration.md
- **Web Object** (analytics SDK):
  - Overview: https://docs.usesophi.com/docs/frontend-integration/web-object.md
  - Configuration: https://docs.usesophi.com/docs/frontend-integration/web-object/configuration.md
  - SophiTracker API: https://docs.usesophi.com/docs/frontend-integration/web-object/sophi-tracker.md
- **Framework guides**: React, Angular under https://docs.usesophi.com/docs/frontend-integration/frameworks/
- **Cookie Consent**: https://docs.usesophi.com/docs/frontend-integration/cookie-consent.md

## Key Rules — Cookie Consent (source: cookie-consent page above)

1. **Web Object stays completely passive until consent is granted** — no session is created and no events are sent.
2. Use the `storageConsent` flag (default `true`) to opt into memory-only pre-consent mode. Set it to `false` before consent to prevent cookies and localStorage writes.
3. Upgrade consent at runtime without interrupting an open chat session:
   - Widget Launcher: `window.sophiWidget.setConsent(true)`
   - Web SDK: `widget.setStorageConsent(true)`
   - Web Object: `window.SophiTracker.setConsent(true)`
4. The chat widget (`sophi-web-sdk`) runs anonymously as a guest before consent — it is a service the visitor explicitly requested. The analytics SDK (`sophi-web-object`) sends **nothing** until consent.

## WORKFLOW — How to Integrate Sophi

When asked to integrate Sophi into a storefront or app, follow these steps:

1. **Fetch the full doc bundle first.**
   ```
   GET https://docs.usesophi.com/llms-full.txt
   ```
   If the task is track-specific, fetch only the relevant `.md` pages listed above instead.

2. **Identify the integration track(s)** from the task description:
   - Catalog/product data → Product Integration track
   - Widget/chat/analytics/events → Frontend Integration track
   - Most stores need both

3. **Follow the documented steps verbatim, and verify every symbol.** Before emitting any Sophi package name, class, method, option, or event name, confirm it appears verbatim in a page you fetched this session (see *Canonical Names* above). Do not invent API shapes, event names, or config keys.

4. **Cite the source doc URL** inline whenever you produce code or configuration. Example: `// ref: https://docs.usesophi.com/docs/frontend-integration/sdk/installation.md`

5. **Apply consent rules by default.** Every Frontend Integration must include the `storageConsent: false` pre-consent pattern unless the project explicitly opts out.

6. **Verify against the live docs** before finalizing. If a symbol or config key you found does not appear in the fetched docs, say so and ask the developer to confirm.

Keep responses concise and operational. Lead with working code, then explain.