Attributie van Visualizer koppelen aan betaalde bestellingen#

Vang de door de Visualizer SDK gepubliceerde attributiesnapshot op, bewaar deze bij het winkelwagentje of de checkout van de klant en meld de definitieve betaalde bestelling vanaf uw server.

De SDK past je winkelwagentje niet automatisch aan en brengt het ook geen bestellingen in kaart. Je integratie moet:

1. de nieuwste snapshot in de storefront vastleggen;
2. de volledige snapshot samen met het winkelwagentje en de bestelling bewaren; en
3. de betaalde bestelling vanaf een vertrouwde server naar Ideal House versturen.

1. De snapshot vastleggen#

Lees de ih_visualizer-cookie wanneer uw storefront initialiseert en luister naar ih:visualizer om updates te ontvangen. De cookie bevat URL-gecodeerde JSON. Het browserevenement biedt hetzelfde object in 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)
}

Implementeer saveAttributionWithCart met de winkelwagentjatributen, checkoutmetadata of de server-side sessie API van uw commerceplatform.

De velden van de snapshot zijn:

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

Sla de volledige snapshot tegelijk op en vervang deze. Hernoem, kopieer niet gedeeltelijk of wijzig de waarden niet. Beschouw gegevens uit een cookie als onbetrouwbaar en verwijder ze als ze niet een volledig object met deze structuur zijn.

Als uw checkout een ander hostnaam of een extern platform gebruikt, kopieer de snapshot dan naar het winkelwagentje of de server-side sessie voordat de klant de storefront-pagina verlaat.

2. Het bij de bestelling bewaren#

Wanneer de betaling rond is, herbouw de originele snapshot vanuit uw winkelwagentje, checkout of bestellingsmetadata. Als er geen complete snapshot beschikbaar is, gebruik dan null in plaats van een gedeeltelijk object samen te stellen.

Bewaar het snapshot als een JSON-waarde of gebruik deze aanbevolen metadatavelden:

Zet idealhouse_categories vóór het indienen van de bestelling weer om naar een JSON-stringarray.

3. De betaalde bestelling indienen#

Roep dit endpoint aan vanaf uw backend of paid-order webhook-handler. Nooit vanaf een browser JavaScript.

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

Gebruik referenties voor dezelfde Ideal House-shop als de storefront SDK. Voeg geen shop_id of shopId toe aan de request body.

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

Verzend monetaire bedragen als JSON-strings. Voeg een tijdzone toe aan elk tijdstip. Verstuur alleen de gedocumenteerde velden; klantnamen, e-mailadressen, telefoonnummers en factuur- of verzendadressen worden niet geaccepteerd.

Voor een bestelling zonder complete attributiesnapshot is het visualizer-veld nog steeds verplicht:

{
  "visualizer": null
}

4. Retry's afhandelen#

Maak een stabiele event_id voor de betaalde-bestelling-gebeurtenis en hergebruik deze voor elke retry.

Voorbeeld van een succesreactie:

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

5. Integratiechecklist#

1. Bevestig dat de storefront ih_visualizer kan lezen na gebruik van de Visualizer.
2. Bevestig dat de ih:visualizer-listener winkelwagentje of checkoutmetadata bijwerkt.
3. Bevestig dat de volledige snapshot de betaalde bestelling bereikt.
4. Dien een betaalde testbestelling vanaf uw server in en verwacht HTTP 200.
5. Dien hetzelfde evenement opnieuw in met dezelfde event_id en accepteer duplicate: true als succes.
6. Dien een bestelling zonder attributie in met behulp van "visualizer": null.
7. Bevestig dat Client Secret en persoonsgegevens van klanten nooit verschijnen in browserrequests of ingediende bestellingsdata.