# Sophi Documentation

> Sophi is an agentic-commerce platform, integrated via two packages:
> `@usesophi/sophi-web-sdk` (chat widget) and `@usesophi/sophi-web-object` (tracking).
> Full text: /llms-full.txt · any page as Markdown: append `.md` · agent skill: /skill.md
> Use only APIs documented on the linked pages — there is no `@sophi/sdk` package or `.track()` method.

- [Get Started](/docs/get-started): What Sophi is, how to pick your integration path, and a 5-minute quick start to send your first event.
- [Sophi Documentation](/docs): Build with Sophi — agentic commerce for your store.
- [Cookie Consent Management](/docs/frontend-integration/cookie-consent): How to keep Sophi usable from the first page view while respecting GDPR/KVKK cookie rules.
- [Frontend Integration](/docs/frontend-integration): Embed the Sophi assistant widget, track storefront events, and manage cookie consent with framework guides for React and Angular.
- [Placement Guide](/docs/placement-guide): Where the Sophi assistant appears in your storefront — eight entry points across search, discovery, product, cart and checkout, and how to choose between them.
- [Navigation & Checkout](/docs/placement-guide/navigation-checkout): Placements 07 and 08 — pin an Ask AI entry to the navigation menu, and answer delivery and returns questions in the cart with the shopper's real basket in context.
- [On-Page Triggers](/docs/placement-guide/on-page): Placements 03 and 04 — build a floating trigger that opens the assistant from any page, and a homepage banner widget that answers delivery and returns questions up front.
- [Product Pages](/docs/placement-guide/product-pages): Placements 05 and 06 — open the assistant with a product already in context from the PDP buy box, and add an Ask AI overlay to every card on a listing page.
- [Search & Recovery](/docs/placement-guide/search): Placements 01 and 02 — put an Ask AI entry point in the storefront search bar, and recover zero-result searches with a guided Sophi panel instead of a dead end.
- [Sophi Ürün Feed Rehberi / Product Feed Guide](/docs/product-integration/feed-guide): Complete specification for the Sophi product XML feed — required fields, variant grouping rules, product attributes, and common mistakes.
- [Product Integration](/docs/product-integration): Connect your product catalog to Sophi via a structured XML feed. Covers feed format, field reference, variant rules, and a sample feed.
- [Sample Feed XML](/docs/product-integration/sample-feed): A working XML feed example with 2 products and 4 variants, covering all required fields, variant grouping, product attributes, and care instructions.
- [Match Your Brand](/docs/shopify/appearance): Style the Sophi Shopify blocks and chat button to match your theme with the Sophi appearance app embed — corners, chip colours, icon, banner alignment, chat-button font and custom CSS — with a live demo of every setting.
- [Test and Go Live](/docs/shopify/go-live): Test the Sophi assistant on an unpublished Shopify theme copy with a preview link, publish it, assign the chat page template, roll back if needed, and fix the most common setup problems.
- [Shopify Integration](/docs/shopify): Put the Sophi assistant on a Shopify store with the Sophi Shopify app — catalog sync, chat entry points, cart and checkout hand-off, and purchase tracking, set up from the theme editor without writing code.
- [Create and Install the App](/docs/shopify/install-app): Create the Sophi app in your Shopify organization's Dev Dashboard, deploy the Sophi app code to it, install it on your store with its six permissions, and share its credentials so Sophi can sync your catalog.
- [Before You Start](/docs/shopify/requirements): What the Sophi Shopify app needs — store plan and theme, the six app permissions and why each is needed, the customer data it shares, and the details to send Sophi before setup.
- [Set Up the Theme](/docs/shopify/theme-setup): Click-by-click theme editor setup for the Sophi Shopify app — work on a theme copy, create the chat page and its template, fill in every Sophi assistant setting, and place the banner, product box, search recovery and cart blocks.
- [Events and Purchases](/docs/shopify/tracking): How the Sophi Shopify app tracks storefront events and purchases — the events it sends, the purchase pixel Sophi creates, how Shopify consent controls both, and how guest and logged-in shoppers are recognised.
- [AI Coding Agents](/docs/use-with-ai): Install the Sophi skill so your AI coding agent — Codex, Claude Code, Cursor, Windsurf — integrates Sophi into your storefront for you, reading the live docs as it works.
- [Angular Integration](/docs/frontend-integration/frameworks/angular): Angular integration guide with basic (full-page and modal) and advanced widget methods for Sophi.
- [Framework Integrations](/docs/frontend-integration/frameworks): Drop-in integration guides for embedding the Sophi assistant widget in React and Angular apps.
- [React Integration](/docs/frontend-integration/frameworks/react): React integration guide with basic (full-page and modal) and advanced widget methods for Sophi.
- [Events](/docs/frontend-integration/sdk/events): The widget exposes an event-driven API. Attach listeners in your application and keep business logic there.
- [GTM Integration](/docs/frontend-integration/sdk/gtm-integration): Load the Sophi Web SDK via Google Tag Manager with consent-aware script injection and app-side initialization.
- [SDK Overview](/docs/frontend-integration/sdk): Use @usesophi/sophi-web-sdk to embed the Sophi assistant in your storefront and handle widget events in your application code.
- [Initialization](/docs/frontend-integration/sdk/initialization): Initialize the widget in your application after the SDK is loaded and the target container is available in the DOM.
- [Installation](/docs/frontend-integration/sdk/installation): Install @usesophi/sophi-web-sdk from npm and initialize the SophiWidget in your storefront.
- [Methods](/docs/frontend-integration/sdk/methods): Reference for the SophiWidget instance methods — lifecycle (init, destroy, isReady), visibility, cart updates, sending messages and product replies, and event subscription.
- [Security Best Practices](/docs/frontend-integration/sdk/security-best-practices): Use these practices when integrating the widget in production environments.
- [Configuration](/docs/frontend-integration/web-object/configuration): All runtime settings for the Sophi Web Object, provided via window.sophi_object.config including apiKey, userId, maxRetries, debounceMs, debug, and storageConsent.
- [Event types](/docs/frontend-integration/web-object/event-types): Events sent to the backend use ExternalEventType on the envelope. Values are lowercase snake-case strings.
- [Data and auth flows](/docs/frontend-integration/web-object/flows): Overview of the event pipeline, auth flow, and session lifecycle for the Sophi Web Object SDK.
- [GTM integration](/docs/frontend-integration/web-object/gtm-integration): How to load @usesophi/sophi-web-object (the storefront event-tracking SDK) through Google Tag Manager, including recommended split and all-in-GTM configurations.
- [Sophi Web Object (@usesophi/sophi-web-object)](/docs/frontend-integration/web-object): The Sophi Web Object package is a framework-agnostic browser SDK that tracks e-commerce behaviour via window.sophi_object and sends structured events to the Sophi event API.
- [Installation](/docs/frontend-integration/web-object/installation): The npm package is @usesophi/sophi-web-object. Artifacts live under dist/ in the package.
- [Integration guide](/docs/frontend-integration/web-object/integration-guide): How to deliver @usesophi/sophi-web-object to your storefront — choose between GTM, npm/bundler, or CDN script tag depending on your stack.
- [Integration patterns](/docs/frontend-integration/web-object/integration-patterns): Common integration patterns for page views, SPA navigation, cart events, purchases, and user login/logout using the Sophi Web Object SDK.
- [SophiTracker API](/docs/frontend-integration/web-object/sophi-tracker): After the bundle loads, window.SophiTracker exposes the public imperative API for SPAs, batched updates, login/logout events, and multi-object pushes such as add_to_cart.
- [Types reference](/docs/frontend-integration/web-object/types): TypeScript type definitions for all Sophi Web Object data structures including PageObject, UserObject, ProductObject, BasketObject, and EventEnvelope.
- [Validation](/docs/frontend-integration/web-object/validation): Before an event is sent, @usesophi/sophi-web-object runs client-side field validation; failures log a console.warn and the event is skipped without any network request.
- [The window.sophi_object layer](/docs/frontend-integration/web-object/window-object): The global window.sophi_object follows the SophiObjectShape — a config block, an optional event-type override, and optional context objects (page, user, product, basket, listing, transaction) that trigger event collection when assigned.