Połącz atrybucję z Visualizer z płatnymi zamówieniami#

Zachwyć migawkę atrybucji opublikowaną przez Visualizer SDK, przechowuj ją wraz z koszykiem lub procesem kasy klienta oraz zgłaszaj ostateczne zamówienie opłacone z zaufanego serwera.

SDK nie modyfikuje Twojego koszyka ani nie raportuje zamówień automatycznie. Twoja integracja musi:

1. przechwycić najnowszy uchwyt w witrynie sklepu;
2. zachować kompletny uchwyt razem z koszykiem i zamówieniem; oraz
3. wysłać płatne zamówienie do Ideal House z zaufanego serwera.

1. Przechwyć uchwyt#

Odczytaj ciasteczko ih_visualizer podczas inicjalizacji witryny sklepu i nasłuchuj zdarzenia ih:visualizer, aby otrzymywać aktualizacje. Ciasteczko zawiera kodowanie URL obiektu JSON. Zdarzenie w przeglądarce dostarcza ten sam obiekt w 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)
}

Zaimplementuj saveAttributionWithCart za pomocą atrybutów koszyka platformy handlowej, metadanych finalizacji zakupów lub sesji po stronie serwera API.

Pola snapshotu to:

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

Przechowuj i zastępuj kompletny snapshot jako całość. Nie zmieniaj nazw, nie kopiuj częściowo ani nie modyfikuj jego wartości. Traktuj dane odczytane z pliku cookie jako niezaufane i odrzuć je, jeśli nie są kompletnym obiektem o tej strukturze.

Jeśli finalizacja zakupów odbywa się pod inną nazwą hosta lub na zewnętrznej platformie, skopiuj uchwyt do koszyka lub sesji po stronie serwera przed opuszczeniem strony przez klienta.

2. Zachowaj go razem z zamówieniem#

Po sfinalizowaniu płatności odtwórz oryginalny uchwyt z metadanych koszyka, finalizacji zakupów lub zamówienia. Jeśli kompletny uchwyt nie jest dostępny, użyj null zamiast konstruowania niekompletnego obiektu.

Przechowuj snapshot jako wartość JSON lub użyj tych zalecanych pól metadanych:

Przed zgłoszeniem zamówienia przekształć idealhouse_categories z powrotem na tablicę stringów JSON.

3. Zgłoś płatne zamówienie#

Wywołaj ten endpoint z poziomu backendu lub handlera webhook płatnego zamówienia. Nigdy nie wywołuj go z przeglądarkowego JavaScript.

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

Użyj danych uwierzytelniających dla tej samej witryny Ideal House co storefront SDK. Nie dołączaj shop_id ani shopId do ciała żądania.

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"
    }
  }'

Wysyłaj wartości pieniężne jako ciągi JSON. Do każdego znacznika czasu dołącz strefę czasową. Wysyłaj tylko udokumentowane pola; imiona i nazwiska klientów, adresy e-mail, numery telefonów oraz adresy rozliczeniowe lub dostawy nie są akceptowane.

Dla zamówienia bez kompletnego uchwytu atrybucji pole visualizer nadal jest wymagane:

{
  "visualizer": null
}

4. Obsłuż ponowne próby#

Utwórz stabilny event_id dla zdarzenia zamówienia opłaconego i wykorzystaj go przy każdym ponownym próbie.

Przykładowa odpowiedź sukcesu:

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

5. Checklista integracji#

1. Potwierdź, że witryna sklepu może odczytać ih_visualizer po użyciu Visualizer.
2. Potwierdź, że nasłuchiwanie ih:visualizer aktualizuje metadane koszyka lub finalizacji zakupów.
3. Upewnij się, że kompletny snapshot trafia do opłaconego zamówienia.
4. Złóż testowe płatne zamówienie z serwera i oczekuj odpowiedzi HTTP 200.
5. Złóż to samo wydarzenie ponownie z tym samym event_id i zaakceptuj duplicate: true jako sukces.
6. Złóż zamówienie testowe bez atrybucji, używając "visualizer": null.
7. Potwierdź, że Client Secret oraz dane osobowe klienta nigdy nie pojawiają się w żądaniach przeglądarkowych ani w przesłanych danych zamówienia.