> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartally.co/llms.txt > Use this file to discover all available pages before exploring further. # Woocommerce Here you can find instructions on how to install and configure the Cartally AI Search widget in your WooCommerce store. ## Installation ### Step 1 — Add the widget script Add the script to your theme's `footer.php` file, just before ``: 1. In the WordPress admin, go to **Appearance → Theme File Editor**. 2. Open `footer.php` (or `theme-footer.php` in block themes). 3. Paste the following code just before the `` tag: ```html theme={null} ``` 4. Click **Update File**. > **Tip:** To prevent losing the script after a theme update, use a **child theme**. If you're already using a child theme, edit its `footer.php` instead. ### Step 2 — Configure settings in the Cartally panel 1. Log in to [app.cartally.co](https://app.cartally.co). 2. Go to **Integration** and enter your store's URL. 3. Select **WooCommerce** as the platform. 4. Provide your **Consumer Key** and **Consumer Secret** (generated in WooCommerce → Settings → Advanced → REST API). 5. Click **Save & Connect** — Cartally will verify the connection and start syncing products. #### Generating WooCommerce API keys 1. In your WordPress admin, go to **WooCommerce → Settings → Advanced → REST API**. 2. Click **Add key**. 3. Set a **Description** (e.g., "Cartally"). 4. Set **Permissions** to **Read**. 5. Click **Generate API key**. 6. Copy the **Client Key** and **Private Key** — paste them in the Cartally integration panel. > **Security:** Read-only permissions are sufficient. Cartally never modifies your products or orders. ### Step 3 — Customize the widget Go to **Widget** in the Cartally panel sidebar to set: * **Accent Color** — the main brand color used in the widget UI. * **Logo URL** — a publicly accessible URL to your store's logo. ## Widget configuration options You can customize the widget by adding `data-` attributes to the script tag: | Attribute | Description | Example | | --------------------------- | ---------------------------------------- | ----------------------------- | | `data-color-accent-primary` | Accent color (hex) | `#e63946` | | `data-logo-url` | URL to your shop logo | `https://myshop.com/logo.png` | | `data-language` | Force a specific language | `en` | | `data-currency` | Force a specific currency | `USD` | | `data-trigger-selector` | CSS selector for custom trigger elements | `.search-btn` | ### Full example with all options ```html theme={null} ``` ## Automatic language and currency detection The widget **automatically detects** the language and currency that the customer is currently using, so you typically don't need to set `data-language` or `data-currency` manually. On WooCommerce the widget reads: * **Language** — from the `` attribute (set by WordPress based on the active locale or WPML/Polylang plugin). * **Currency** — from the `.woocommerce-Price-currencySymbol` element on the page and maps the symbol to an ISO code (e.g., `$` → `USD`, `€` → `EUR`, `zł` → `PLN`). This means if your store uses a multi-currency plugin (e.g., WPML, Aelia Currency Switcher, or Currency Switcher for WooCommerce), the widget will match the customer's current selection. > You can override the automatic detection by explicitly setting `data-language` and `data-currency` on the script tag. This is recommended if your multi-currency plugin does not render `.woocommerce-Price-currencySymbol` on every page. ## Attaching the widget to any element The widget can be triggered by **any element on the page** — a button, link, icon, or any other HTML element. You choose the element by providing its CSS class or ID in the `data-trigger-selector` attribute. ### Option A — Use `data-trigger-selector` on the script tag Specify a CSS selector (class or ID) that matches the element(s) you want to use as the widget trigger: ```html theme={null} ``` You can pass multiple selectors separated by commas: ```html theme={null} data-trigger-selector=".search-btn, #header-search, .mobile-search-icon" ``` ### Option B — Add a class directly to the element If you prefer, add the `cartally-trigger` class to any element in your theme: ```html theme={null} Search ``` ### Common WooCommerce theme selectors | Theme | Selector | | ------------- | ---------------------------------------- | | Storefront | `.site-search`, `.site-header .search` | | Astra | `.ast-search-icon`, `.astra-search-icon` | | OceanWP | `#searchform-header .search-toggle` | | Flatsome | `.icon-search`, `.searchform-wrapper` | | GeneratePress | `.navigation-search` | > **Tip:** To find the correct selector for your theme, right-click the search element in your browser → **Inspect** → note the `class` or `id` of the element. ## Multilingual support Cartally automatically detects and indexes products in all languages configured in your WooCommerce store. * Search works in the language currently selected by the customer. * Autocomplete suggestions match the store's active language. * Compatible with **WPML**, **Polylang**, and **TranslatePress**. * If a product is not translated, the store's default language is used. ## Currencies and localization Cartally supports currencies configured in your store. * Customers always see prices in their currently selected currency. * The widget auto-detects the active currency from the page. * If a price is not available in a given currency, the store's default currency is used. ## Product synchronization Products are synchronized with Cartally via the WooCommerce REST API. * An initial full sync runs when you first connect the integration. * Subsequent syncs run periodically to keep the catalog up to date. * You can trigger a re-sync from the **Integration** page in the Cartally dashboard. ## Troubleshooting ### Widget does not appear Check if: * The script tag is present in the page source (View Source or F12 → Elements). * The `src` URL (`https://app.cartally.co/widget.js`) is not blocked by a Content Security Policy, ad blocker, or security plugin (e.g., Wordfence). * There are no JavaScript errors in the browser console (F12 → Console). * If using a caching plugin, clear the cache after adding the script. ### Products not appearing in search Check if: * The product is **published** (not draft or private). * The product has a **name** and **description**. * The WooCommerce REST API keys have **Read** permissions. * The sync job has completed (check **Integration** page in the Cartally panel). * Your site is accessible from external servers (not blocked by `.htaccess`, Cloudflare firewall rules, or IP restrictions). ### Wrong language or currency If the widget shows the wrong language or currency: * Check `document.documentElement.lang` in the browser console — it should match the active language. * Check if `.woocommerce-Price-currencySymbol` is present on the page (inspect a product price element). * If detection fails, set `data-language` and `data-currency` explicitly on the script tag. ### AI does not respond or is slow Possible reasons: * The AI request limit has been reached. * There is temporary system overload. * The query is very complex. Solution: Check **Dashboard → Usage Overview → AI Requests** in the Cartally panel. ### Caching conflicts If the widget behaves inconsistently: * Exclude `widget.js` from caching in your performance plugin (WP Super Cache, W3 Total Cache, LiteSpeed Cache). * The widget script has `defer` so it should not block page rendering. * If using Cloudflare Rocket Loader, add `data-cfasync="false"` to the script tag.