Status
| Part | What it does |
|---|---|
| Storefront widgets | Loader on every page, an Idukki UGC gallery CMS widget, and an optional gallery on product pages filtered to that product. |
| Catalogue | Enabled, visible products (configurable products with their children as variants), a daily full sync plus product changes every 5 minutes. |
| Orders | Each placed order, with the Idukki visitor id, sent without blocking checkout and retried from a queue. |
| Status panel | Connected or not, last catalogue sync, last order sent, retry queue size. |
| Add to cart in the gallery | Built into the widget for Magento and arriving with early access; until it is on for your store, product taps open the product page. |
Requirements
- Magento Open Source or Adobe Commerce 2.4.4 or later, PHP 8.1 to 8.4.
- Magento cron running every minute (
bin/magento cron:run). Catalogue changes, Sync now and order retries all run from cron. - An Idukki account, your Business ID (the
data-bguidin any Idukki embed code) and at least one gallery ID (data-guid). - A store connection key for this Magento store (see Connect).
Install
We share the module with early-access stores. Install it with Composer or copy it into app/code.
composer require idukkidev/idukki-magento-extension
bin/magento module:enable Idukki_PairConnect
bin/magento setup:upgrade
bin/magento setup:di:compile # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flushcp -r app/code/Idukki <magento-root>/app/code/
cd <magento-root>
bin/magento module:enable Idukki_PairConnect
bin/magento setup:upgrade && bin/magento cache:flushConnect with a store connection key
In the Idukki dashboard open Settings, then the Magento tab under Integrations, and create a key in the Store connection card. Early-access accounts have the tab switched on for them.
The key starts with idk_pc_ and is shown once, when you create it. Idukki keeps only a hash of it, so a lost key cannot be shown again: revoke it and make a new one. One key belongs to one store and one platform; a Magento key is refused by a PrestaShop store. Revoking a key in the dashboard stops the module at once.
- In Magento open Stores, Configuration, Idukki, Idukki UGC.
- Under Connection paste the key and your Business ID. Leave the API base URL at
https://api.idukki.io. - Click Test connection. It calls
GET /webhooks/partner/pingwith the key and shows what Idukki answered, even for a key you have typed but not saved. Then Save Config. - Under Catalogue sync click Sync catalogue now to queue the first full sync, or run
bin/magento idukki:catalogue:syncto send it straight away.
The key is stored encrypted, marked sensitive so app:config:dump never writes it to config.php, and only a masked prefix is ever shown back. The connection is a website-scope setting: one key at Default Config serves the whole install (the catalogue is then sent once, from the default website), or give each website its own key to sync each catalogue separately. Titles, URLs, images and prices come from each website’s default store view.
Place galleries
Every gallery needs the Business ID saved and Load Idukki on the storefront switched on (it is on by default). The page loads https://idukki-cdn.com/dist/loader.js once, async.
| Where | How |
|---|---|
| CMS pages and blocks | Content, Widgets, Add Widget, Idukki UGC gallery, or Insert Widget in the CMS editor. Leave the gallery ID empty to use the default gallery. |
| Page Builder | Drag a Text or HTML Code element, click Insert Widget, choose Idukki UGC gallery. This uses Magento’s standard widget insertion and has not been checked on a live Page Builder install. |
| Product pages | Set Show a gallery on product pages to Yes. It sits above related products with filter-pid set to the product’s entity id (the parent id for configurable products). Move it with <move element="idukki.product.gallery" destination="product.info.main"/> in catalog_product_view.xml. |
<div data-ugc="idukki" data-bguid="..." data-guid="..." filter-pid="<product id>" data-platform="magento"></div>The module’s csp_whitelist.xml allows https://idukki-cdn.com and https://*.idukki.io, and the inline loader carries Magento’s CSP nonce where one is enforced.
Cookie consent
| Setting | Behaviour |
|---|---|
| Follow Magento cookie restriction mode (default) | With restriction mode off, the loader loads normally. With it on, the loader is added only after the shopper allows cookies, including right after they click Allow Cookies. |
| Wait for my consent manager | Never loads by itself. Your consent tool calls window.idukkiConsentGranted() or dispatches idukki:consent-granted on document. |
| Do not wait for consent | Always loads. |
The decision runs in the browser, so full-page cache never serves one visitor’s consent state to another. Until the loader runs, galleries do not render and no visitor id cookie is written.
What data is sent
| Call | Data |
|---|---|
| Catalogue | Product ids, SKUs, names, product URLs, image URLs, final and regular prices, currency, stock flags, configurable children. At most 250 products per request to POST /webhooks/partner/catalogue. |
| Orders | Order id and number, time, currency, total, status, line items (product and variant ids, SKU, quantity, unit price), the Magento customer id for logged-in shoppers, the quote id and the Idukki visitor id. One request per order to POST /webhooks/partner/orders. |
| Never sent | Shopper names, emails, phone numbers, billing or shipping addresses, IP addresses or payment data. |
Every call goes over HTTPS with the key in an Authorization: Bearer header. The module refuses a non-https API base except localhost.
How orders are matched to widget activity
When an order is placed, the module reads the visitor id cookie the Idukki loader writes (idk-vid, then the older idk_vid) and sends it with the order. It is read only for orders placed from the shopper’s own browser; orders created in the admin are sent without one. Checkout is never blocked: one attempt with a 3-second timeout, then the order waits in the idukki_outbox table and is retried by cron for about a day and a half. Idukki ignores a repeat of the same order id.
Idukki matches each order to widget activity through the visitor id first, then the customer id and the cart id. An order counts as proven only when the same visitor added a product they bought to the cart from the widget beforehand. Orders that only followed a widget view or click land in the influence tiers, and the rest are store orders. The dashboard keeps proven, influenced and store orders in separate columns and never adds them together.
Troubleshooting
| Symptom | Check |
|---|---|
| Key rejected by Idukki | Copied incompletely, revoked, or made for another platform. Create a new Magento key. |
| Key saved, not verified yet never changes | Cron is not running. Check cron_schedule for idukki_pairconnect_queue and idukki_pairconnect_product_sync. |
| No gallery | Business ID saved for that website, loader on, a gallery ID set, the consent setting, and the browser console for CSP errors. |
| Product page gallery empty | The product needs tagged posts in Idukki, and the catalogue must have synced so the ids match. |
| Products missing in Idukki | Enabled, on the website and visible individually. Skipped products are listed in var/log/idukki.log. |
| Orders not matched | The visitor id exists only once the loader has run in that browser (consent, CSP). Headless storefronts that place orders server-side without the shopper’s cookies send no visitor id. |
Every failed call, sync summary and skipped product is logged to var/log/idukki.log.
Uninstall
bin/magento module:uninstall Idukki_PairConnect --remove-data
bin/magento cache:flushThat removes every idukki/* config value (including the encrypted key), the idukki_* flags and the idukki_outbox table. An app/code install needs module:disable, deleting the folder and the SQL cleanup listed in the module README. Either way, revoke the key in the Idukki dashboard as well.