Visualizer-Attribution mit bezahlten Bestellungen verknüpfen#

Erfassen Sie den vom Visualizer SDK veröffentlichten Attribution-Snapshot, behalten Sie ihn beim Warenkorb oder Checkout des Kunden bei und melden Sie die endgültige bezahlte Bestellung von Ihrem Server.

Das SDK ändert nicht Ihren Warenkorb oder meldet Bestellungen automatisch. Ihre Integration muss:

1. Den aktuellsten Snapshot im Onlineshop erfassen;
2. Den vollständigen Snapshot zusammen mit dem Warenkorb und der Bestellung aufbewahren; und
3. Die bezahlte Bestellung von einem vertrauenswürdigen Server an Ideal House senden.

1. Den Snapshot erfassen#

Lesen Sie das ih_visualizer Cookie bei der Initialisierung Ihres Onlineshops und lauschen Sie auf ih:visualizer, um Aktualisierungen zu empfangen. Das Cookie enthält URL-codiertes JSON. Das Browser-Ereignis liefert dasselbe Objekt 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)
}

Implementieren Sie saveAttributionWithCart mit den Warenkorbattributen, Checkout-Metadaten oder serverseitigen Session-API-Mechanismen Ihrer Commerce-Plattform.

Die Snapshot-Felder sind:

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

Speichern und ersetzen Sie den vollständigen Snapshot gemeinsam. Benennen Sie nicht um, kopieren Sie nicht teilweise und ändern Sie keine Werte. Betrachten Sie Daten aus einem Cookie als nicht vertrauenswürdig und verwerfen Sie sie, wenn es sich nicht um ein vollständiges Objekt mit dieser Struktur handelt.

Wenn Ihr Checkout einen anderen Hostname oder eine externe Plattform verwendet, kopieren Sie den Snapshot in den Warenkorb oder die serverseitige Session, bevor der Kundendie Onlineshop-Seite verlässt.

2. Mit der Bestellung aufbewahren#

Wenn die Zahlung abgeschlossen ist, rekonstruieren Sie den ursprünglichen Snapshot aus den Warenkorb-, Checkout- oder Bestelldaten. Wenn kein vollständiger Snapshot verfügbar ist, verwenden Sie null anstelle eines unvollständigen Objekts.

Speichern Sie den Snapshot als JSON-Wert oder verwenden Sie diese empfohlenen Metadatenfelder:

Konvertieren Sie idealhouse_categories vor der Übermittlung der Bestellung zurück in ein JSON-String-Array.

3. Die bezahlte Bestellung melden#

Rufen Sie diesen Endpunkt aus Ihrem Backend oder dem Webhook-Handler für bezahlte Bestellungen auf. Rufen Sie ihn niemals aus browserseitigem JavaScript auf.

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

Verwenden Sie Zugangsdaten für denselben Ideal House-Shop wie das Onlineshop-SDK. Fügen Sie shop_id oder shopId nicht im Anfragebody ein.

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

Senden Sie Geldwerte als JSON-Strings. Geben Sie bei jedem Zeitstempel eine Zeitzone an. Senden Sie nur die dokumentierten Felder; Kundennamen, E-Mail-Adressen, Telefonnummern sowie Rechnungs- oder Versandadressen werden nicht akzeptiert.

Für eine Bestellung ohne vollständigen Attributions-Snapshot ist das visualizer-Feld weiterhin erforderlich:

{
  "visualizer": null
}

4. Wiederholungen verarbeiten#

Erstellen Sie eine stabile event_id für das Bezahlungs-Ereignis und wiederverwenden Sie sie bei jedem Wiederholungsversuch.

Beispiel einer erfolgreichen Antwort:

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

5. Checkliste zur Integration#

1. Stellen Sie sicher, dass der Onlineshop ih_visualizer nach Nutzung des Visualizers lesen kann.
2. Stellen Sie sicher, dass der ih:visualizer-Listener Warenkorb- oder Checkout-Metadaten aktualisiert.
3. Bestätigen Sie, dass der vollständige Snapshot die bezahlte Bestellung erreicht.
4. Übermitteln Sie eine bezahlte Testbestellung von Ihrem Server und erwarten Sie HTTP 200.
5. Übermitteln Sie dasselbe Ereignis erneut mit derselben event_id und akzeptieren Sie duplicate: true als Erfolg.
6. Übermitteln Sie eine Bestellung ohne Attribution mittels "visualizer": null.
7. Stellen Sie sicher, dass Client Secret und personenbezogene Kundendaten niemals in Browser-Anfragen oder übermittelten Bestelldaten erscheinen.