Collegare l'attribuzione del Visualizer agli ordini pagati#

Acquisire la snapshot di attribuzione pubblicata dallo Visualizer SDK, conservarla con il carrello o il checkout del cliente e inviare l'ordine pagato finale dal tuo server.

L'SDK non modifica il tuo carrello né segnala gli ordini automaticamente. La tua integrazione deve:

1. acquisire l'ultima snapshot nel storefront;
2. conservare la snapshot completa insieme al carrello e all'ordine; e
3. inviare l'ordine pagato a Ideal House da un server attendibile.

1. Acquisire la snapshot#

Leggere il cookie ih_visualizer quando il tuo storefront si inizializza e ascolta ih:visualizer per ricevere aggiornamenti. Il cookie contiene JSON codificato in URL. L'evento browser fornisce lo stesso oggetto 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)
}

Implementa saveAttributionWithCart con gli attributi del carrello della tua piattaforma Commerce, i metadati del checkout o la sessione lato server API.

I campi della snapshot sono:

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

Memorizza e sostituisci la snapshot completa insieme. Non rinominare, copiare parzialmente o modificare i suoi valori. Trattaine i dati letti da un cookie come non attendibili e scartali se non costituiscono un oggetto completo con questa struttura.

Se il tuo checkout utilizza un altro hostname o una piattaforma esterna, copia la snapshot nel carrello o nella sessione lato server prima che il cliente lasci la pagina dello storefront.

2. Conservarla con l'ordine#

Al completamento del pagamento, ricostruisci la snapshot originale dai metadati del carrello, del checkout o dell'ordine. Se non è disponibile una snapshot completa, usa null invece di costruire un oggetto parziale.

Salva lo snapshot come valore JSON oppure utilizza questi campi metadata consigliati:

Converti idealhouse_categories in un array di stringhe JSON prima di inviare l'ordine.

3. Inviare l'ordine pagato#

Chiama questo endpoint dal backend o dal gestore webhook dell'ordine pagato. Non chiamarlo mai dal JavaScript del browser.

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

Usa le credenziali dello stesso negozio Ideal House del storefront SDK. Non includere shop_id o shopId nel corpo della richiesta.

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

Invia i valori monetari come stringhe JSON. Includi un fuso orario in ogni timestamp. Invia solo i campi documentati; i nomi dei clienti, gli indirizzi email, i numeri di telefono e gli indirizzi di fatturazione o spedizione non sono accettati.

Per un ordine privo di una snapshot di attribuzione completa, il campo visualizer è comunque obbligatorio:

{
  "visualizer": null
}

4. Gestire i retry#

Crea un event_id stabile per l'evento dell'ordine pagato e riutilizzalo per ogni nuovo tentativo.

Esempio di response di successo:

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

5. Checklist di integrazione#

1. Conferma che lo storefront possa leggere ih_visualizer dopo aver utilizzato il Visualizer.
2. Conferma che l'ascoltatore ih:visualizer aggiorni i metadati del carrello o del checkout.
3. Conferma che la snapshot completa raggiunga l'ordine pagato.
4. Invia un ordine di test pagato dal tuo server e attenditi HTTP 200.
5. Invia nuovamente lo stesso evento con lo stesso event_id e accetta duplicate: true come successo.
6. Invia un ordine senza attribuzione utilizzando "visualizer": null.
7. Conferma che il Client Secret e i dati personali del cliente non appaiano mai nelle richieste del browser o nei dati dell'ordine inviato.