` or the provided `` container: ```html ... ``` The grid shows results in batches of 12 with a **Show more** button (up to 50 per search). Column width is the "Grid column width" setting in the widget designer. ### Add image search to your existing search bar Already have a search you're happy with? Embed only the camera button inside (or next to) your own search bar and point it at a results container anywhere in the page: ```html ``` `data-icon-only="true"` renders just the 📷 button — no input, no styling around it — so it drops into any existing markup. Image search is always on in this mode. If the results target is missing, matches fall back to a small dropdown anchored to the icon. ### All attributes | Attribute | Meaning | |---|---| | `data-key` | **Required.** Your publishable key. | | `data-num` | How many results (default 12 in dropdown mode, 24 in page mode, max 50). | | `data-placeholder` | Input placeholder text (default "Search products…"). | | `data-image` | `"true"` adds the search-by-photo camera button. | | `data-display` | `"page"` renders results as an in-flow grid below the input instead of a dropdown. | | `data-results-target` | CSS selector of the element to render the results grid into. | | `data-icon-only` | `"true"` renders only the camera button, for embedding in your own search bar. | | `data-currency` | Currency symbol for prices (dashboard setting wins when configured). | | `data-api` | Override the API base URL (rarely needed — it is baked into the script). | ## `` — shoppable images Shows the published Look for a product (created and published from your dashboard's Shop-the-Look page): ```html ``` Renders nothing if no published look exists for that product, so it is safe to place on every product page. ## Conversion tracking Views and clicks on recommendations are tracked by the widgets automatically. **Add-to-carts and purchases are not** — the widgets can't see your cart button or your checkout, so your storefront must report those two events itself. (The WooCommerce plugin does both for you; this section is for custom storefronts.) **Add-to-cart** — call from your add-to-cart handler, after the add succeeds: ```html ``` Alternatively, configure a custom DOM event name under the dashboard's widget "Storefront events" and dispatch it instead: `document.dispatchEvent(new CustomEvent('my:add-to-cart', {detail: {item_id: '123', value: 49.9}}))`. **Purchase** — fire from the order-confirmation page, once per line item: ```html ``` …or sync the whole order server-side with `POST /v1/orders` (see the [API reference](v1-api-reference.md)). `ProductRecs` is available after the recommendations script loads. ### Attribution: keep the shopper id consistent The Impact dashboard credits an add-to-cart or sale to the recommender only when the commerce event and an earlier rec click/impression carry the **same shopper identity and product id** (30-day window). Identity is `user_id` when present, otherwise the widget's automatic session id — and `user_id` always wins when both are sent. So: - **Logged-in shoppers**: pass the customer id everywhere — `data-user-id` on every widget embed, `user_id` on your `add-to-cart`/`buy` calls, and `user_id` on `POST /v1/orders`. If the widgets run anonymous while orders carry a customer id, nothing matches and attribution stays at zero. - **Anonymous shoppers**: the widget keeps its session id in `localStorage["pr_sid"]`. Browser-side `ProductRecs.track` calls pick it up automatically. For server-side order sync, mirror it into a first-party cookie and forward it as `session_id`: ```html ``` ## Appearance Fonts, colors, buttons, and layout come from your dashboard's widget designer and are fetched live by the widget — one source of truth, changes are instant. Custom CSS can be added in the designer, or override the widget's classes in your own stylesheet. ### Google Analytics If your store runs GA4 (`gtag`), you can enable the analytics passthrough in the dashboard: widget interactions are mirrored as standard GA4 events tagged `item_list_id="basketbooster"`, so results show up in your own reports. ## Gotchas - **HTTPS stores need the HTTPS API base** — browsers block `http://` calls from `https://` pages. - **Origin allowlist** — a publishable key with an empty allowlist accepts any origin. If you set an allowlist in the dashboard, include every domain the widget runs on. See [publishable-keys-and-cors](publishable-keys-and-cors.md). - The widget renders nothing (not an error) when the key is missing or no anchor is provided — check the browser console and attributes first.