Görselleştirici atıfını ödenmiş siparişlere bağlayın#

Visualizer SDK tarafından yayınlanan atıf anlık görüntüsünü yakalayın, müşterinin sepeti veya ödeme sırasında yanında tutun ve nihai ödenmiş siparişi sunucunuzdan bildirin.

SDK, sepetinizi otomatik olarak değiştirmez veya siparişleri raporlamez. Entegrasyonunuz şunları yapmalıdır:

1. en güncel anlık görüntüyü mağaza vitrininde yakalamak;
2. tam anlık görüntüyü sepet ve siparişle birlikte tutmak; ve
3. ödenmiş siparişi güvenilir bir sunucudan Ideal House'a göndermek.

1. Anlık görüntüyü yakalayın#

Mağaza vitrininiz başlatıldığında ih_visualizer çerezini okuyun ve güncellemeleri almak için ih:visualizer'ı dinleyin. Çerez, URL ile kodlanmış JSON içerir. Tarayıcı olayı aynı nesneyi event.detail içinde sağlar.

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'ı e-ticaret platformunuzun sepet özellikleri, ödeme meta verileri veya sunucu tarafı oturum API ile uygulayın.

Snapshot alanları şunlardır:

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

Tam snapshot'ı birlikte depolayın ve değiştirin. Alan adlarını değiştirmeyin, kısmi kopyalama yapmayın veya değerlerini düzenlemeyin. Çerezden okunan veriyi güvenilmez olarak kabul edin ve bu yapıya sahip tam bir nesne değilse göz ardı edin.

Ödemeniz farklı bir ana bilgisayar adı kullanıyorsa veya harici bir platform ise, müşteri mağaza vitrini sayfasını terk etmeden önce anlık görüntüyü sepete veya sunucu tarafı oturumuna kopyalayın.

2. Siparişle birlikte tutun#

Ödeme tamamlandığında, anlık görüntüyü sepetinizden, ödeme bilgilerinden veya sipariş meta verilerinden yeniden oluşturun. Tam bir anlık görüntü mevcut değilse, kısmi bir nesne oluşturmaktansa null kullanın.

Snaphot'u bir JSON değeri olarak saklayın veya bu önerilen metadata alanlarını kullanın:

Siparişi bildirirken idealhouse_categories'ı JSON diziğine dönüştürün.

3. Ödenmiş siparişi bildirin#

Bu uç noktaı backend'inizden veya ödenmiş sipariş webhook işleyicinizden çağırın. Asla tarayıcı JavaScript'ından çağırmayın.

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

Mağaza vitrini SDK ile aynı Ideal House dükkanı için kimlik bilgilerini kullanın. İstek gövdesine shop_id veya shopId eklemeyin.

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

Para değerlerini JSON dizeleri olarak gönderin. Her zaman damgasına bir saat dilimi ekleyin. Yalnızca belgelenmiş alanları gönderin; müşteri adları, e-posta adresleri, telefon numaraları ve fatura veya kargo adresleri kabul edilmez.

Tam atıf anlık görüntüsü olmayan bir sipariş için visualizer alanı hala gereklidir:

{
  "visualizer": null
}

4. Yeniden denemeleri yönetin#

Ödeme yapılan sipariş olayı için tutarlı bir event_id oluşturun ve her yeniden denemede onu yeniden kullanın.

Başarılı yanıt örneği:

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

5. Entegrasyon kontrol listesi#

1. Mağaza vitrininin Görselleştirici'yi kullandıktan sonra ih_visualizer'i okuyabildiğinden emin olun.
2. ih:visualizer dinleyicisinin sepeti veya ödeme meta verilerini güncellediğinden emin olun.
3. Tam snapshot'ın ödenmiş siparişe ulaştığını doğrulayın.
4. Sunucunuzdan ödenmiş bir test siparişi gönderin ve HTTP 200 bekleyin.
5. Aynı event_id ile olayı tekrar gönderin ve duplicate: true'u başarı olarak kabul edin.
6. Atıf olmadan bir sipariş göndermek için "visualizer": null kullanın.
7. Client Secret ve müşteri kişisel verilerinin asla tarayıcı isteklerinde veya gönderilen sipariş verilerinde görünmediğinden emin olun.