SDK Overview

Use @usesophi/sophi-web-sdk to embed the Sophi assistant in your storefront and handle widget events in your application code.

For storefront event tracking without the widget (page, product, basket, purchase, etc.), use the separate package @usesophi/sophi-web-object — see the Web Object documentation.

Required for production

Every customer integration should include these three items:

1. Handle add_to_cart event.
2. Handle send_to_checkout event.
3. Call widget.updateUserCart(cart) whenever host cart data changes.

Without these, cart synchronization and checkout handoff will be incomplete.

Security reminder

• Keep real keys and tokens out of docs, GTM tags, and static frontend bundles.
• Use placeholders such as YOUR_SOPHI_API_KEY.
• Keep sensitive values server-side when possible.

What this SDK provides

• Framework-agnostic widget initialization
• Browser script support via window.SophiWebSDK
• Typed events for commerce actions
• Runtime methods for user/cart updates and widget lifecycle

Public API surface

• Class: SophiWidget
• Init: await widget.init(config)
• Events: ready, add_to_cart, add_to_favorite, send_to_checkout, error
• Methods: on, off, updateUserCart, sendToggleHistory, sendTextMessage, sendProductReply, openProductById, triggerProductReply, show, hide, isReady, destroy

Step-by-step integration path

1. Access widget object from window (if script/GTM mode) or npm import.
2. Initialize widget.
3. Wire required events (add_to_cart, send_to_checkout).
4. Sync cart via updateUserCart.
5. Add advanced methods (sendToggleHistory, sendProductReply, triggerProductReply) only if needed.

Recommended reading order:

• GTM Integration for loading and troubleshooting script/runtime errors
• Events for required event handlers
• Methods for required cart sync and advanced controls
• Framework guides for copy-paste React/Angular examples (basic and advanced)

Documentation map