Drupal Commerce-Einrichtungsanleitung

Architecture

Emporiqa uses your store catalog as its knowledge base: the module pushes products, variations, prices, stock and content pages over webhooks as you save them, so there is no separate knowledge base you have to write or keep up to date. For anything your shop pages never covered, you can write a page yourself on the Pages screen in the Emporiqa dashboard: a title and the text in your own words, in up to 10 languages on the same page. You write each language yourself, and any of them can carry a link to the same page on your site. The chat answers from it like it answers from any page your shop sent, and a sync never overwrites it. Up to 25 pages per store. On the Products screen you can set up to 50 products to Promoted or Top: the chat shows them first when they match what the shopper asked, Top before Promoted, and never shows them for unrelated questions. A sync never clears it.

The module listens to entity CRUD hooks (hook_entity_insert, hook_entity_update, hook_entity_delete) for Commerce products, variations, and configured node types. Events are pushed onto a dedicated Drupal queue worker and delivered to Emporiqa asynchronously, so saving a product completes locally while the webhook delivery runs in the background. From version 1.1.1 a request that queued changes sends up to 20 of them right after its response has gone out, so they reach Emporiqa within seconds instead of at the next cron run; cron sends the rest. To turn this off, set $settings['emporiqa_send_after_save'] = FALSE; in settings.php.

All translations and channels for a single product or page consolidate into one webhook event. Variations cascade up: editing a variation triggers a parent product re-sync so search always sees the full catalog state. Conversion tracking is handled by an event subscriber on Commerce order state transitions (OrderCompleteSubscriber).

Webhook delivery retries up to 3 times on transient errors (HTTP 429, 502, 503, 504) and network failures, with linear backoff between attempts. The queue is processed by Drupal's cron. If the queue grows past 10,000 items, a warning is logged (typically meaning the webhook endpoint is unreachable or cron isn't running).

Requirements

Configuration Reference

All settings live at Configuration → Web services → Emporiqa (/admin/config/services/emporiqa). The Sync tab lives at /admin/config/services/emporiqa/sync. The administer emporiqa permission is required. A Ready-made rules section shows the Order status address.

Connection Settings

Sync Settings

Most stores don't need to change these.

Field Auto-detection

On install, the module auto-detects your product fields (category, brand, images, stock, attributes) from the Commerce product and variation entity schemas. The mappings are stored in config and can be adjusted on the settings form.

Page Sync via Display Modes

Pages are synced using Drupal's native display modes, no custom code needed. The module creates an Emporiqa display on install and enables it for common content types (page, article).

1. Go to Structure → Content types → [Your type] → Manage display.
2. Enable the Emporiqa tab.
3. Drag the fields you want synced into that display.

The rendered output of the Emporiqa display becomes the page content sent to the webhook. Different content types can expose different fields, all configured through Drupal's admin, no module code touched. The same approach works for product descriptions when the Emporiqa display is enabled on a product type.

Always-on capabilities

• Cart operations: add, update, and remove items from inside the chat via /emporiqa/api/cart/*. Checkout happens on your Commerce checkout page; the widget redirects when the customer is ready.
• Conversion tracking: chat sessions linked to completed Commerce orders for revenue attribution.
• Multi-store mapping: each Commerce store can be assigned a channel via hook_emporiqa_channels_alter.

Features

Webhook Payload

Each product or page is sent as a single webhook event containing all languages and channels. Translatable fields are nested by channel and language code.

Product Event

{
  "type": "product.updated",
  "data": {
    "identification_number": "product-42",
    "sku": "product-42",
    "channels": [""],
    "names":        {"": {"en": "Hiking Boots", "de": "Wanderschuhe"}},
    "descriptions": {"": {"en": "Waterproof leather boots...", "de": "Wasserdichte Lederstiefel..."}},
    "links":        {"": {"en": "https://store.com/hiking-boots", "de": "https://store.com/de/wanderschuhe"}},
    "categories":   {"": {"en": ["Footwear > Hiking"], "de": ["Schuhe > Wandern"]}},
    "attributes":   {"": {"en": {"Material": "Leather"}, "de": {"Material": "Leder"}}},
    "brands":       {"": "TrailPeak"},
    "prices":       {"": [{"currency": "EUR", "current_price": 129.99, "regular_price": 149.99}]},
    "images":       {"": ["https://store.com/files/boots-front.jpg"]},
    "availability_statuses": {"": "available"},
    "stock_quantities":      {"": 42},
    "min_order_quantities":  {"": 1},
    "max_order_quantities":  {"": null},
    "available_for_order": true,
    "condition": null,
    "is_virtual": false,
    "is_parent": false,
    "parent_sku": null,
    "variation_attributes": {}
  }
}

Page Event

{
  "type": "page.created",
  "data": {
    "identification_number": "page-45",
    "channels": [""],
    "titles":   {"": {"en": "Shipping Policy", "de": "Versandrichtlinien"}},
    "contents": {"": {"en": "<p>Rendered Emporiqa display...</p>", "de": "<p>Gerenderte Emporiqa-Anzeige...</p>"}},
    "links":    {"": {"en": "https://store.com/shipping-policy", "de": "https://store.com/de/versandrichtlinien"}}
  }
}

Field Structure

Customization Hooks

The module provides Drupal alter hooks you can implement in a custom module (mymodule.module) to control sync behavior, modify payloads, and extend Order status and cart operations. Full documentation lives in emporiqa.api.php.

Example: skip draft pages

/**
 * Implements hook_emporiqa_entity_sync_alter().
 */
function mymodule_emporiqa_entity_sync_alter(
  bool &$sync,
  \Drupal\Core\Entity\EntityInterface $entity,
  string $entity_type,
  string $operation,
): void {
  if (
    $entity_type === 'page'
    && $entity instanceof \Drupal\node\NodeInterface
    && str_contains($entity->getTitle(), '[DRAFT]')
  ) {
    $sync = FALSE;
  }
}

Example: add tax-inclusive prices

/**
 * Implements hook_emporiqa_price_entry_alter().
 */
function mymodule_emporiqa_price_entry_alter(
  array &$entry,
  array $context,
): void {
  $entry['price_incl_tax'] = round($entry['current_price'] * 1.20, 2);
  $entry['price_excl_tax'] = $entry['current_price'];
}

Example: provide tier prices

/**
 * Implements hook_emporiqa_tier_prices_alter().
 */
function mymodule_emporiqa_tier_prices_alter(
  array &$tier_prices,
  array $context,
): void {
  $variation = $context['variation'];

  if ($variation->hasField('field_tier_prices')) {
    foreach ($variation->get('field_tier_prices') as $item) {
      $tier_prices[] = [
        'min_quantity' => (int) $item->min_qty,
        'price' => (float) $item->price,
        'currency' => $context['currency'],
      ];
    }
  }
}

Example: cancel a cart operation

/**
 * Implements hook_emporiqa_cart_alter().
 */
function mymodule_emporiqa_cart_alter(array &$context): void {
  if ($context['operation'] === 'add') {
    $total_qty = 0;
    foreach ($context['items'] as $item) {
      $total_qty += $item['quantity'] ?? 1;
    }
    if ($total_qty > 10) {
      $context['cancel'] = TRUE;
      $context['cancel_message'] = 'Maximum 10 items per operation.';
    }
  }
}

Drush Commands

The module provides Drush commands for deployment pipelines, cron jobs, and debugging.

# Full sync (products + pages)
drush emporiqa:sync-all         # alias: em:sa

# Sync products only
drush emporiqa:sync-products    # alias: em:sp

# Sync pages only
drush emporiqa:sync-pages       # alias: em:spg

# Test the webhook connection (dry run with a real product)
drush emporiqa:test-connection  # alias: em:tc

# Adjust batch size for large catalogs
drush emporiqa:sync-products --batch-size=25

options:
  uri: 'https://your-store-domain.com'

Order status

The ready-made Order status rule answers "Where is my order?" in the chat. Emporiqa asks your site through the module's signed order_status endpoint and tells the shopper the status, the order date and, with Commerce Shipping, each shipment's tracking number, carrier and tracking link. Carts (draft orders) are never looked up. It needs module version 1.1.0 or newer, and your site must be served over https.

What the shopper sees, what your team gets and how to write your own rules: Rules guide.

Set it up

1. In Drupal, open Configuration → Web services → Emporiqa. The Ready-made rules section shows the Order status address and a Copy button.
2. Click Open in Emporiqa next to Order status. Your Emporiqa dashboard opens at Settings → Rules with Order status highlighted. Click Add.
3. Drupal has no one-click connect, so Emporiqa asks for the address: paste the Order status address under Check my shop and save. Emporiqa checks it with one signed call to your site, then emails the store owners a link. The address is saved once one of them clicks it.
4. Click Try it and ask about one of your recent orders. When it answers correctly, click Go live.

The Order status address looks like this:

Behind a reverse proxy or CDN, set $settings['reverse_proxy'] and $settings['reverse_proxy_addresses'] in settings.php, so the address shows https and the per-address limits see real visitor addresses. On and Not added on the settings page show what Emporiqa said at the last Test Connection; run it again after changing the rule.

What the shopper gives

• Signed in to your shop: only the order number. The module answers only for that customer's own orders.
• Guest: the order number and the email used for the order.

Endpoint

Signed-in customers

When a shopper is signed in to your store, the chat shows them their own prices and uses their account when it hands the conversation to your team. There is nothing to set up: it starts once the module is on the versions below. Guests see your public prices, as before.

• Their own prices, version 1.1.0 or newer: price lists and role-based prices from Commerce Pricelist, with their quantity tiers, as Commerce resolves them for that customer. The chat asks your store through the signed customer_prices action when it shows a product, and shows the answer to that customer only, on the cards, in quotes and in the product details. Coupons and cart rules apply at your checkout, as before, and a search with a price limit ("under 200") is applied to what the customer pays.
• Their name and email, version 1.1.1 or newer (the Customer info action): the chat greets them by first name, and a handoff reaches your team with the name and email on their account, so they are not asked for them.

Both answer only for the customer the module signed in for this store, and only on that customer's own messages: a shopper who signs out is a guest from their next message. Per customer, prices are kept for 5 minutes and the account details for 30. Each customer is limited to 30 requests and each store to 600 every 10 minutes.

Customer info action

From version 1.1.1 the module answers a signed customer_info request about a shopper who is signed in to your site: the name and email on their account (first and last name from the default customer profile) and up to 10 of the account's own placed orders, newest first (order number, date, status, total and currency). Carts, guest orders placed with the same email and other customers' orders are never included. With it, a signed-in shopper who asks "where is my order?" without a number gets their newest order, as long as the Order status rule is on; there is nothing to set up.

Requests are signed like Order status and limited to 30 per customer and 600 per store every 10 minutes. To remove a field or add your own under extra, implement hook_emporiqa_customer_info_alter(), which runs after the answer is built:

/**
 * Implements hook_emporiqa_customer_info_alter().
 */
function mymodule_emporiqa_customer_info_alter(
  array &$data,
  \Drupal\user\UserInterface $account,
): void {
  unset($data['customer']['email']);
  if ($account->hasField('field_loyalty_tier') && !$account->get('field_loyalty_tier')->isEmpty()) {
    $data['extra']['loyalty_tier'] = $account->get('field_loyalty_tier')->value;
  }
}

Updating

After updating to version 1.1.1, run the database updates (they add the empty Shop URL setting and register the new route and services) and clear the cache:

drush updb
drush cr

If the Settings tab then warns about http:// links, set Shop URL to your shop's https address and run Sync All once, so the links already sent are rewritten.

Troubleshooting