Product Feed

`, inline CSS vb.) **olmamalıdır**. Düz metin veya CDATA kullanın. ```xml Güzel bir
ürün ``` ### 10.4 `product_detail` Bloklarının Eksik Olması [#104-product_detail-bloklarının-eksik-olması] Sisteminizde ürün özellikleri (kumaş tipi, kesim, yaka, desen vb.) mevcut olduğu halde bunların `product_detail` blokları ile aktarılmaması. Bu verileri açıklama alanına gömmeyin, yapılandırılmış olarak gönderin. ```xml Örme kumaş, O yaka, kısa kollu bluz Ürün Özellikleri Kumaş Tipi Örme Ürün Özellikleri Yaka Tipi O Yaka ``` ### 10.5 Malzeme Bilgisinin Eksik Olması [#105-malzeme-bilgisinin-eksik-olması] `g:material` alanı özellikle tekstil ve deri ürünlerinde kritik öneme sahiptir. Malzeme bileşimini yüzde oranlarıyla aktarın. ```xml %85 Polyester, %10 Elastan, %5 Metalik Elyaf ``` ### 10.6 Belirsiz Beden Değerleri [#106-belirsiz-beden-değerleri] "40" gibi bir beden değeri giysi, ayakkabı veya yaş grubu olabilir. Mümkünse beden sistemi hakkında ek bilgi verin veya `product_type` kategorisinin beden tipini anlaşılır kılmasını sağlayın. ### 10.7 Boş veya Placeholder Değerler [#107-boş-veya-placeholder-değerler] Gerçek veri olmayan placeholder değerlerden kaçının: * `%100 Diğer` (bilinmeyen malzeme yerine) * `Çok Renkli` (gerçek renk yerine) * Boş etiketler (``) *** ## 11. Dosyalar / Files [#11-dosyalar--files] Bu klasördeki dosyalar: | Dosya | Açıklama | | -------------------------------------------------------- | ------------------------------------------------------------------------ | | `feed-guide.md` | Bu rehber dosyası | | [sample-feed.md](/docs/product-integration/sample-feed) | Dokümantasyon içinde görüntülenebilir XML örneği | | [sample\_feed.xml](/product-integration/sample_feed.xml) | Raw örnek XML feed (2 ürün, 4 varyant, tüm alanlar ve açıklamalar dahil) | `sample_feed.xml` dosyasında: * **Ürün 1** (Bluz, `item_group_id = BLZ-001`): 3 varyant (Siyah S, Siyah M, Beyaz S) - çoklu varyant örneği * **Ürün 2** (Sneaker, `item_group_id = SNK-042`): 1 varyant (Siyah 39) - farklı ürün örneği, ayakkabıya özel özelliklerle Bu iki ürün birlikte, `item_group_id`'nin nasıl çalıştığını gösterir: aynı ürünün varyantları aynı grupta, farklı ürünler farklı gruplarda. # Product Integration URL: /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. Sophi ingests your store's product data through a structured XML feed (RSS 2.0, Google Merchant Center compatible). Once the feed is live, Sophi can match products to user sessions and power agentic recommendations. This track covers everything you need to build and validate your feed. # Sample Feed XML URL: /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. A working reference feed you can validate against. It contains 2 products (4 variants total) with all required and optional fields annotated. * [Download raw XML](/product-integration/sample_feed.xml) * [Back to Product Integration](/docs/product-integration) ```xml Product Feed https://www.example.com Product catalog with detailed attributes BLZ-001-SYA-S Marka Desenli Bluz Siyah https://www.example.com/kadin/bluz/desenli-bluz-siyah-p-BLZ001 https://cdn.example.com/images/blz-001-siyah-01.jpg https://cdn.example.com/images/blz-001-siyah-02.jpg https://cdn.example.com/images/blz-001-siyah-03.jpg https://cdn.example.com/images/blz-001-siyah-04.jpg in_stock MARKA ADI Siyah new female 8680000000001 BLZ-001 1990.00 TRY 1490.00 TRY Giyim > Bluz]]> S %85 Polyester, %10 Elastan, %5 Metalik Elyaf Urun Ozellikleri Kumas Tipi Orme Urun Ozellikleri Kesim Tipi Standart Kalip Urun Ozellikleri Yaka Tipi O Yaka Urun Ozellikleri Kol Tipi Kisa Kollu Urun Ozellikleri Desen Desenli Urun Ozellikleri Yasam Tarzi Casual Urun Ozellikleri Urun Grubu Bluz Bakim Yikama Makinede yikanmaz Bakim Agartma Agartici kullanilmaz Bakim Utuleme Utulenmez Bakim Kuru Temizleme Kuru temizleme yapilabilir (P) Bakim Kurutma Tamburlu makinede kurutulmaz BLZ-001-SYA-M Marka Desenli Bluz Siyah https://www.example.com/kadin/bluz/desenli-bluz-siyah-p-BLZ001 https://cdn.example.com/images/blz-001-siyah-01.jpg https://cdn.example.com/images/blz-001-siyah-02.jpg https://cdn.example.com/images/blz-001-siyah-03.jpg https://cdn.example.com/images/blz-001-siyah-04.jpg out_of_stock MARKA ADI Siyah new female 8680000000002 BLZ-001 1990.00 TRY 1490.00 TRY Giyim > Bluz]]> M %85 Polyester, %10 Elastan, %5 Metalik Elyaf Urun Ozellikleri Kumas Tipi Orme Urun Ozellikleri Kesim Tipi Standart Kalip Urun Ozellikleri Yaka Tipi O Yaka Urun Ozellikleri Kol Tipi Kisa Kollu Urun Ozellikleri Desen Desenli Urun Ozellikleri Yasam Tarzi Casual Urun Ozellikleri Urun Grubu Bluz Bakim Yikama Makinede yikanmaz Bakim Agartma Agartici kullanilmaz Bakim Utuleme Utulenmez Bakim Kuru Temizleme Kuru temizleme yapilabilir (P) Bakim Kurutma Tamburlu makinede kurutulmaz BLZ-001-BYZ-S Marka Desenli Bluz Beyaz https://www.example.com/kadin/bluz/desenli-bluz-beyaz-p-BLZ001 https://cdn.example.com/images/blz-001-beyaz-01.jpg https://cdn.example.com/images/blz-001-beyaz-02.jpg https://cdn.example.com/images/blz-001-beyaz-03.jpg in_stock MARKA ADI Beyaz new female 8680000000003 BLZ-001 1990.00 TRY 1990.00 TRY Giyim > Bluz]]> S %85 Polyester, %10 Elastan, %5 Metalik Elyaf Urun Ozellikleri Kumas Tipi Orme Urun Ozellikleri Kesim Tipi Standart Kalip Urun Ozellikleri Yaka Tipi O Yaka Urun Ozellikleri Kol Tipi Kisa Kollu Urun Ozellikleri Desen Desenli Urun Ozellikleri Yasam Tarzi Casual Urun Ozellikleri Urun Grubu Bluz Bakim Yikama Makinede yikanmaz Bakim Agartma Agartici kullanilmaz Bakim Utuleme Utulenmez Bakim Kuru Temizleme Kuru temizleme yapilabilir (P) Bakim Kurutma Tamburlu makinede kurutulmaz SNK-042-SYA-39 Marka Deri Sneaker Siyah https://www.example.com/erkek/ayakkabi/deri-sneaker-siyah-p-SNK042 https://cdn.example.com/images/snk-042-siyah-01.jpg https://cdn.example.com/images/snk-042-siyah-02.jpg https://cdn.example.com/images/snk-042-siyah-03.jpg in_stock MARKA ADI Siyah new male 8680000000010 SNK-042 3490.00 TRY 2790.00 TRY Ayakkabi > Sneaker]]> 39 %100 Dogal Deri Urun Ozellikleri Urun Grubu Sneaker Urun Ozellikleri Dis Materyal Dogal Deri Urun Ozellikleri Ic Materyal Tekstil Urun Ozellikleri Taban Tipi Kaucuk Urun Ozellikleri Kapama Tipi Bagcikli Urun Ozellikleri Topuk Yuksekligi 3 cm Urun Ozellikleri Yasam Tarzi Casual Urun Ozellikleri Mensei Turkiye Urun Ozellikleri Sezon SS 2025 ``` # AI Coding Agents URL: /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. Point your AI coding agent at Sophi and let it do the integration. Install the **Sophi Agent Skill** and tools like **Codex, Claude Code, Cursor, or Windsurf** can wire Sophi into your storefront for you — reading the live Sophi docs at task time (so the code is always current) and writing the product-feed, Web SDK, and Web Object integration against your codebase. The skill points your agent at `https://docs.usesophi.com/llms-full.txt` (a single-file bundle of all Sophi docs) and the per-page `.md` endpoints. The agent reads the live content on demand instead of relying on training-data memory, then writes the integration. ## Install for Claude Code [#install-for-claude-code] Run this one-liner in your terminal. It downloads the skill into the standard Claude Code skills directory. ```bash mkdir -p ~/.claude/skills/sophi && curl -fsSL https://docs.usesophi.com/skill.md -o ~/.claude/skills/sophi/SKILL.md ``` After installation, Claude Code picks up the skill automatically. Ask it to "integrate Sophi" and it fetches the live docs and writes the code. ## Manual download [#manual-download] Prefer to manage the file yourself? Download it directly: ## Works with any coding agent [#works-with-any-coding-agent] | Agent | Where to put it | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Claude Code** | `~/.claude/skills/sophi/SKILL.md` (global) or `/.claude/skills/sophi/SKILL.md` (project-local) | | **Codex** | `AGENTS.md` at your repo root (Codex reads it automatically) | | **Cursor** | `.cursor/rules/sophi.md` (or `.cursorrules`) | | **Windsurf** | `.windsurf/rules/sophi.md` | | **Any agent** | Point it at `https://docs.usesophi.com/llms-full.txt`, or paste the page index from `https://docs.usesophi.com/llms.txt` | ## Per-page AI actions [#per-page-ai-actions] Every page in these docs has **Copy Markdown** and **Open** actions in the top-right corner: * **Copy Markdown** copies the raw Markdown of the page for pasting into a chat. * **Open** opens the current page in ChatGPT or Claude with the full page text as context. Any page is also readable as Markdown by appending `.md` to its URL: ``` https://docs.usesophi.com/docs/frontend-integration/sdk/installation.md ``` ## LLM-friendly endpoints [#llm-friendly-endpoints] | Endpoint | Contents | | --------------------------------------------------- | ------------------------------------------------------------------------- | | `https://docs.usesophi.com/llms-full.txt` | All Sophi docs concatenated — ideal for one-shot context injection | | `https://docs.usesophi.com/llms.txt` | Page index with titles and URLs — ideal for retrieval-augmented workflows | | `https://docs.usesophi.com/.md` | Any individual page as clean Markdown | | `https://docs.usesophi.com/skill.md` · `/AGENTS.md` | The installable agent skill | # Angular Integration URL: /docs/frontend-integration/frameworks/angular Angular integration guide with basic (full-page and modal) and advanced widget methods for Sophi. This page is organized in two levels: * **Basic setup**: copy-paste examples for full-page and modal usage * **Advanced setup**: optional runtime controls (`sendToggleHistory`, `sendProductReply`, `triggerProductReply`) For GTM script loading and script-load failures, use [SDK GTM troubleshooting](/docs/frontend-integration/sdk/gtm-integration#troubleshooting). ## Required in every integration [#required-in-every-integration] No matter which UI pattern you use (full page or modal), implement all three: 1. Handle `add_to_cart` 2. Handle `send_to_checkout` 3. Call `widget.updateUserCart(cart)` when cart changes ## Basic setup [#basic-setup] ## 1) Access object from `window` [#1-access-object-from-window] ```ts const SophiWidgetClass = (window as any).SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) { throw new Error("Sophi SDK not loaded yet"); } ``` ## 2) Initialize widget [#2-initialize-widget] ```ts const widget = new SophiWidgetClass(); await widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-container", environment: "production", }); ``` ## 3) Full-page minimal example [#3-full-page-minimal-example] ```ts import { AfterViewInit, Component, Input, OnChanges, OnDestroy, SimpleChanges } from "@angular/core"; import { Router } from "@angular/router"; type CartItem = { productId: string; variantId?: string; quantity: number }; @Component({ selector: "app-sophi-full-page", template: `

`, }) export class SophiFullPageComponent implements AfterViewInit, OnChanges, OnDestroy { @Input() cartId = ""; @Input() cartItems: CartItem[] = []; private widget: any = null; constructor(private readonly router: Router) {} async ngAfterViewInit(): Promise { const SophiWidgetClass = (window as any).SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) return; this.widget = new SophiWidgetClass(); await this.widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-container", environment: "production", width: "100%", height: "100%", }); this.widget.on("add_to_cart", async (data: { products: Array<{ productId: string; variantId?: string }> }) => { for (const product of data.products) { await addToCartInYourApp(product.productId, product.variantId); } }); this.widget.on("send_to_checkout", () => { this.router.navigateByUrl("/checkout"); }); this.syncCart(); } ngOnChanges(changes: SimpleChanges): void { if (!this.widget) return; if (changes["cartId"] || changes["cartItems"]) { this.syncCart(); } } private syncCart(): void { this.widget.updateUserCart({ cartId: this.cartId, items: this.cartItems, }); } async ngOnDestroy(): Promise { await this.widget?.destroy?.(); this.widget = null; } } ``` ## 4) Modal minimal example [#4-modal-minimal-example] ```ts import { Component, Input, OnChanges, OnDestroy, SimpleChanges } from "@angular/core"; import { Router } from "@angular/router"; @Component({ selector: "app-sophi-modal", template: ` `, }) export class SophiModalComponent implements OnChanges, OnDestroy { @Input() cartId = ""; @Input() cartItems: Array<{ productId: string; variantId?: string; quantity: number }> = []; isOpen = false; private widget: any = null; constructor(private readonly router: Router) {} async open(): Promise { this.isOpen = true; if (this.widget) return; const SophiWidgetClass = (window as any).SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) return; this.widget = new SophiWidgetClass(); await this.widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-modal-container", environment: "production", width: "100%", height: "100%", }); this.widget.on("add_to_cart", async (data: { products: Array<{ productId: string; variantId?: string }> }) => { for (const product of data.products) { await addToCartInYourApp(product.productId, product.variantId); } }); this.widget.on("send_to_checkout", () => { this.close(); this.router.navigateByUrl("/checkout"); }); this.syncCart(); } close(): void { this.isOpen = false; } ngOnChanges(changes: SimpleChanges): void { if (!this.widget) return; if (changes["cartId"] || changes["cartItems"]) { this.syncCart(); } } private syncCart(): void { this.widget.updateUserCart({ cartId: this.cartId, items: this.cartItems, }); } async ngOnDestroy(): Promise { await this.widget?.destroy?.(); this.widget = null; } } ``` ## 5) Required events and cart sync wiring [#5-required-events-and-cart-sync-wiring] ```ts widget.on("add_to_cart", async (data) => { for (const product of data.products) { await addToCartInYourApp(product.productId, product.variantId); } }); widget.on("send_to_checkout", () => { router.navigateByUrl("/checkout"); }); widget.updateUserCart({ cartId: cartId, items: cartItems, }); ``` ## Advanced setup [#advanced-setup] Call advanced methods only after `ready` event or `widget.isReady()`: ```ts widget.on("ready", () => { widget.sendToggleHistory(); widget.triggerProductReply(product); widget.sendProductReply("Can you tell me more about this item?", product); }); ``` * `sendToggleHistory`: open/close history panel * `triggerProductReply`: prefill product reply context * `sendProductReply`: send product-context query ## Consent-aware (pre-consent memory-only mode) [#consent-aware-pre-consent-memory-only-mode] To make the assistant available **before** the visitor accepts cookies, initialize with `storageConsent: false` and upgrade in place when consent is granted. See [Cookie Consent Management](/docs/frontend-integration/cookie-consent) for the full concept. Initialize the widget **once** with the initial consent value, then call `setStorageConsent(true)` whenever your consent service emits a grant — do not destroy and re-create the widget, or the open chat is lost. ```ts import { AfterViewInit, Component, OnDestroy } from "@angular/core"; import { Subscription } from "rxjs"; import { ConsentService } from "./consent.service"; // your own service @Component({ selector: "app-sophi-consent-aware", template: `

`, }) export class SophiConsentAwareComponent implements AfterViewInit, OnDestroy { private widget: any = null; private sub?: Subscription; constructor(private readonly consent: ConsentService) {} async ngAfterViewInit(): Promise { const SophiWidgetClass = (window as any).SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) return; this.widget = new SophiWidgetClass(); await this.widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-container", environment: "production", width: "100%", height: "100%", storageConsent: this.consent.hasConsent(), // false → memory-only }); // Upgrade the live widget in place when consent is granted. this.sub = this.consent.changes$.subscribe((granted: boolean) => { if (granted) { void this.widget?.setStorageConsent?.(true); } }); } async ngOnDestroy(): Promise { this.sub?.unsubscribe(); await this.widget?.destroy?.(); this.widget = null; } } ``` ## Security [#security] * Keep `YOUR_SOPHI_API_KEY` as placeholder in docs * Do not put real secrets or internal endpoints into client code examples # Framework Integrations URL: /docs/frontend-integration/frameworks Drop-in integration guides for embedding the Sophi assistant widget in React and Angular apps. Framework-specific guides live in this section. # React Integration URL: /docs/frontend-integration/frameworks/react React integration guide with basic (full-page and modal) and advanced widget methods for Sophi. This page is organized in two levels: * **Basic setup**: copy-paste patterns that customers can run with minimal edits * **Advanced setup**: optional runtime controls (`sendToggleHistory`, `sendProductReply`, `triggerProductReply`) For GTM script loading and script-load failures, use [SDK GTM troubleshooting](/docs/frontend-integration/sdk/gtm-integration#troubleshooting). ## Required in every integration [#required-in-every-integration] No matter which UI pattern you use (full page or modal), implement all three: 1. Handle `add_to_cart` 2. Handle `send_to_checkout` 3. Call `widget.updateUserCart(cart)` when cart changes ## Basic setup [#basic-setup] ## 1) Access object from `window` [#1-access-object-from-window] If you load SDK via GTM or script tag: ```ts const SophiWidgetClass = window.SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) { throw new Error("Sophi SDK not loaded yet"); } ``` ## 2) Initialize widget [#2-initialize-widget] ```ts const widget = new SophiWidgetClass(); await widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-container", environment: "production", }); ``` ## 3) Full-page minimal example [#3-full-page-minimal-example] ```tsx import { useEffect, useRef } from "react"; declare global { interface Window { SophiWebSDK?: { SophiWidget: new () => any }; } } type Cart = { cartId: string; items: Array<{ productId: string; variantId?: string; quantity: number }>; }; export function SophiFullPage({ cart }: { cart: Cart }) { const widgetRef = useRef(null); useEffect(() => { const SophiWidgetClass = window.SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) return; const widget = new SophiWidgetClass(); widgetRef.current = widget; (async () => { await widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-container", environment: "production", width: "100%", height: "100%", }); widget.on("add_to_cart", async (data: { products: Array<{ productId: string; variantId?: string }> }) => { for (const p of data.products) { await addToCartInYourApp(p.productId, p.variantId); } }); widget.on("send_to_checkout", () => { window.location.href = "/checkout"; }); widget.updateUserCart({ cartId: cart.cartId, items: cart.items, }); })(); return () => { widgetRef.current?.destroy?.(); widgetRef.current = null; }; }, [cart.cartId, cart.items]); useEffect(() => { if (!widgetRef.current) return; widgetRef.current.updateUserCart({ cartId: cart.cartId, items: cart.items, }); }, [cart.cartId, cart.items]); return

; } ``` ## 4) Modal minimal example [#4-modal-minimal-example] ```tsx import { useEffect, useRef, useState } from "react"; export function SophiModal({ cart }: { cart: { cartId: string; items: any[] } }) { const [open, setOpen] = useState(false); const widgetRef = useRef(null); useEffect(() => { if (!open) return; const SophiWidgetClass = window.SophiWebSDK?.SophiWidget; if (!SophiWidgetClass) return; if (widgetRef.current) return; const widget = new SophiWidgetClass(); widgetRef.current = widget; (async () => { await widget.init({ apiKey: "YOUR_SOPHI_API_KEY", container: "#sophi-widget-modal-container", environment: "production", width: "100%", height: "100%", }); widget.on("add_to_cart", async (data: { products: Array<{ productId: string; variantId?: string }> }) => { for (const p of data.products) { await addToCartInYourApp(p.productId, p.variantId); } }); widget.on("send_to_checkout", () => { setOpen(false); window.location.href = "/checkout"; }); widget.updateUserCart({ cartId: cart.cartId, items: cart.items, }); })(); return () => { widgetRef.current?.destroy?.(); widgetRef.current = null; }; }, [open, cart.cartId, cart.items]); useEffect(() => { if (!widgetRef.current) return; widgetRef.current.updateUserCart({ cartId: cart.cartId, items: cart.items, }); }, [cart.cartId, cart.items]); return ( <> {open && (