Skip to main content

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.

Here you can find instructions on how to install and configure the Cartally AI Search widget in your PrestaShop store.

​
Installation

​
Step 1 — Add the widget script

Open your PrestaShop back office and edit the theme template files. You can do this via FTP or through Design → Theme & Logo → Advanced customization (if your theme supports it). Add the following code to one of these files in your theme directory (themes/your-theme/templates/_partials/):
  • head.tpl — inside the <head> section (recommended — the defer attribute ensures the script loads after the page)
  • footer.tpl — just before the closing </body> tag
<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
></script>
Tip: Using head.tpl is preferred because it’s less likely to be overridden by theme updates. The defer attribute guarantees the script won’t block page rendering.

​
Step 2 — Generate a Webservice API key

Cartally needs a read-only API key to sync your product catalog.
  1. In the PrestaShop back office, go to Advanced Parameters → Webservice.
  2. Make sure the Webservice is enabled (toggle at the top of the page).
  3. Click Add new webservice key (the ”+” button).
  4. In the Key field, click Generate to create a random key, or enter your own.
  5. In the Permissions section, enable GET (read) access for the following resources:
    • products
    • categories
    • images
    • manufacturers
    • combinations (if you use product variants)
    • product_options and product_option_values (for attributes like size, color)
    • languages
    • currencies
  6. Leave all other permissions (PUT, POST, DELETE) unchecked.
  7. Click Save.
  8. Copy the generated API key.
Security: Only read (GET) permissions are required. Cartally never modifies your products, orders, or any other data.

​
Step 3 — Configure settings in the Cartally panel

  1. Log in to app.cartally.co.
  2. Go to Integration and enter your store’s URL.
  3. Select PrestaShop as the platform and paste the API key from Step 2.
  4. Click Save & Connect — Cartally will verify the connection and start syncing products.

​
Step 4 — 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:
AttributeDescriptionExample
data-color-accent-primaryAccent color (hex)#e63946
data-logo-urlURL to your shop logohttps://myshop.com/logo.png
data-languageForce a specific languagepl
data-currencyForce a specific currencyPLN
data-trigger-selectorCSS selector for custom trigger elements.search-btn

​
Full example with all options

<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
  data-color-accent-primary="#e63946"
  data-logo-url="https://myshop.com/img/logo.png"
  data-language="pl"
  data-currency="PLN"
  data-trigger-selector=".cartally-trigger, .header-search-btn"
></script>

​
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 PrestaShop 1.7+ and 8.x the widget reads:
  • Language — from prestashop.language.iso_code (the global JS object available on every front-office page).
  • Currency — from prestashop.currency.iso_code.
This means if your store supports multiple languages and currencies, the widget will match the customer’s current selection automatically.
You can still override the automatic detection by explicitly setting data-language and data-currency on the script tag.

​
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: 
<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
  data-trigger-selector=".my-search-button"
></script>
You can pass multiple selectors separated by commas: 
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 template: 
<!-- Using a class -->
<a href="#" class="search-icon cartally-trigger">
  <i class="material-icons">search</i>
</a>

​
PrestaShop Classic theme example

The default search form in the Classic theme has the selector #search_widget. To replace it: 
data-trigger-selector="#search_widget"
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 PrestaShop store.
  • Search works in the language currently selected by the customer.
  • Autocomplete suggestions match the store’s active language.
  • 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 reads the active currency from PrestaShop automatically.
  • 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 PrestaShop Webservice 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 placed before </body> in your theme template.
  • The src URL (https://app.cartally.co/widget.js) is not blocked by a Content Security Policy or ad blocker.
  • There are no JavaScript errors in the browser console (F12 → Console).
Check if:
  • The product is active (not disabled) in PrestaShop.
  • The product has a name and description.
  • The Webservice API key has read permissions for Products, Categories, and Images.
  • The sync job has completed (check Integration page in the Cartally panel).

​
Wrong language or currency

If the widget shows the wrong language or currency:
  • Verify that prestashop.language.iso_code and prestashop.currency.iso_code are available in your browser console.
  • If they are missing (custom theme), 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.