Подключение атрибуции Визуализатора к оплаченным заказам#

Зафиксируйте снимок атрибуции, публикуемый Visualizer SDK, сохраните его вместе с корзиной или оформлением заказа клиента и отправьте данные об итоговом оплаченном заказе с вашего сервера.

SDK не изменяет вашу корзину и не отправляет заказы автоматически. Ваша интеграция должна:

1. захватывает последний снимок на витрине;
2. сохраняет полный снимок вместе с корзиной и заказом; и
3. отправляет оплаченный заказ в Ideal House с доверенного сервера.

1. Захват снимка#

При инициализации витрины прочитайте куки ih_visualizer и прослушивайте событие ih:visualizer для получения обновлений. Куки содержат URL-кодированные данные в формате JSON. Браузерное событие предоставляет тот же объект в поле event.detail.

function readVisualizerAttribution() {
  const prefix = 'ih_visualizer='
  const value = document.cookie
    .split(';')
    .map(part => part.trim())
    .find(part => part.startsWith(prefix))
    ?.slice(prefix.length)

  if (!value) return null

  try {
    return JSON.parse(decodeURIComponent(value))
  } catch {
    return null
  }
}

window.addEventListener('ih:visualizer', event => {
  saveAttributionWithCart(event.detail)
})

const currentAttribution = readVisualizerAttribution()
if (currentAttribution) {
  saveAttributionWithCart(currentAttribution)
}

Реализуйте функцию saveAttributionWithCart через атрибуты корзины вашей коммерческой платформы, метаданные оформления заказа или серверный сеанс с использованием API.

Поля снимка состояния:

{
  "visitor_id": "anonymous-visitor-id",
  "session_id": "visualizer-session-id",
  "categories": ["wall", "furniture"],
  "last_used_at": "2026-09-10T12:34:56.000Z"
}

Сохраняйте и перезаписывайте полный снимок состояния целиком. Не переименовывайте, не копируйте частично и не изменяйте его значения. Считайте данные, прочитанные из cookie, ненадёжными, и отбрасывайте их, если они не являются полным объектом указанной структуры.

Если ваш процесс оформления заказа работает на другом домене или использует внешнюю платформу, скопируйте снимок атрибуции в корзину или серверную сессию до того, как клиент покинет страницу витрины.

2. Сохраняйте его вместе с заказом#

После завершения платежа восстановите исходный снимок из метаданных вашей корзины, оформления заказа или самого заказа. Если полного снимка нет, используйте значение null, а не формируйте частичный объект.

Сохраняйте снимок в виде значения JSON или используйте следующие рекомендуемые поля метаданных:

Перед отправкой заказа преобразуйте idealhouse_categories обратно в массив строковых значений JSON.

3. Отчет об оплаченном заказе#

Вызывайте этот эндпоинт из бэкенда или обработчика webhook оплаченного заказа. Никогда не вызывайте его из браузерного кода на JavaScript.

POST <IDEALHOUSE_API_URL>/integrations/commerce/order-events
Content-Type: application/json
X-Client-Id: <CLIENT_ID>
X-Client-Secret: <CLIENT_SECRET>

Используйте учетные данные для того же магазина Ideal House, что и SDK витрины. Не включайте поля shop_id или shopId в тело запроса.

curl -X POST "<IDEALHOUSE_API_URL>/integrations/commerce/order-events" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-Client-Secret: <CLIENT_SECRET>" \
  -d '{
    "schema_version": 1,
    "event_id": "store-42-order-paid-1001",
    "event_type": "order.paid",
    "source": {
      "platform": "custom",
      "store_id": "store-42"
    },
    "order": {
      "id": "order-1001",
      "order_number": "#1001",
      "customer_po_number": null,
      "created_at": "2026-09-10T11:55:00.000Z",
      "paid_at": "2026-09-10T12:00:00.000Z",
      "financial_status": "paid",
      "currency": "USD",
      "subtotal": "125.50",
      "total": "143.25",
      "line_items": [
        {
          "id": "line-1",
          "product_id": "product-1",
          "variant_id": "variant-1",
          "sku": "WP-100",
          "product_type": "Wallpaper",
          "quantity": 2,
          "unit_price": "62.75",
          "total_price": "125.50"
        }
      ]
    },
    "visualizer": {
      "visitor_id": "anonymous-visitor-id",
      "session_id": "visualizer-session-id",
      "categories": ["wall", "furniture"],
      "last_used_at": "2026-09-09T12:00:00.000Z"
    }
  }'

Отправляйте денежные значения в виде строк JSON. Указывайте часовой пояс в каждом значении времени. Отправляйте только поля, описанные в документации; имена клиентов, адреса электронной почты, номера телефонов и адреса выставления счетов или доставки не принимаются.

Для заказа без полного снимка атрибуции поле visualizer всё равно обязательно:

{
  "visualizer": null
}

4. Обработка повторных попыток#

Создайте стабильный event_id для события об оплате заказа и используйте его при каждой попытке повторной отправки.

Пример успешного ответа:

{
  "accepted": true,
  "duplicate": false,
  "visualizer_assisted": true
}

5. Контрольный список интеграции#

1. Убедитесь, что витрина может считать ih_visualizer после использования Визуализатора.
2. Убедитесь, что обработчик события ih:visualizer обновляет метаданные корзины или оформления заказа.
3. Убедитесь, что полный снимок состояния передаётся вместе с оплаченным заказом.
4. Отправьте тестовый оплаченный заказ с вашего сервера и ожидайте ответ HTTP 200.
5. Отправьте то же самое событие повторно с тем же event_id и примите результат duplicate: true как успешный.
6. Отправьте заказ без атрибуции, указав "visualizer": null.
7. Убедитесь, что Client Secret и персональные данные клиентов никогда не появляются в браузерных запросах или передаваемых данных заказа.