ビジュアライザーの属性を注文確定まで連携する#

Visualizer SDKが公開する属性スナップショットを取得し、顧客のカートやチェックアウトに保持してから、サーバーから最終的な注文確定情報を送信してください。

SDKは carrito や注文を自動的に変更したり報告したりしません。統合では以下の操作が必要です。

ストアフロントで最新の snapshot を取得すること；
完全なスナップショットをカートと注文に保持すること；および
信頼できるサーバーから注文確定情報をIdeal Houseに送信すること。

1. スナップショットの取得#

ストアフロントの初期化時にih_visualizerクッキーを読み込み、ih:visualizerイベントを監視して更新を受け取ってください。クッキーにはURLエンコードされたJSONが含まれています。ブラウザイベントでは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)
}

eCommerceプラットフォームのカート属性、チェックアウトメタデータ、またはサーバーサイドセッションAPIを使ってsaveAttributionWithCartを実装してください。

スナップショットのフィールドは次のとおりです。

json

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

完全なスナップショットをまとめて保存および置換してください。フィールド名を変更したり、部分的にコピーしたり、値を変更したりしないでください。Cookie から読み取ったデータは信頼できないものとして扱い、この形状の完全なオブジェクトでない場合は破棄してください。

チェックアウトが別のホスト名や外部プラットフォームを使用している場合は、顧客がストアフロントページを離れる前にスナップショットをカートまたはサーバーサイドセッションにコピーしてください。

2. 注文と一緒に保持する#

支払い完了時に、カート、チェックアウト、または注文メタデータから元のスナップショットを復元してください。完全なスナップショットがない場合は、部分的なオブジェクトを構築する代わりにnullを使用してください。

スナップショットを JSON 値として保存するか、以下の推奨メタデータフィールドを使用してください：

メタデータフィールド	値
`idealhouse_visitor_id`	`visitor_id`
`idealhouse_session_id`	`session_id`
`idealhouse_categories`	`categories`をカンマで連結
`idealhouse_last_used_at`	`last_used_at`

注文送信前にidealhouse_categoriesをJSON文字列配列に戻してください。

3. 注文確定を報告する#

このエンドポイントへの呼び出しはバックエンドまたは成約済み注文のWebフックハンドラから行ってください。ブラウザのJavaScriptから呼び出さないでください。

http

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

ストアフロントSDKと同じIdeal Houseショップの認証情報を使用してください。リクエストボディにshop_idやshopIdを含めないでください。

bash

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

金銭的価値は JSON 文字列として送信してください。すべてのタイムスタンプにはタイムゾーンを含めてください。文書化されたフィールドのみを送信してください。顧客名、メールアドレス、電話番号、請求先または配送先住所は受け入れられません。

完全な属性スナップショットがない注文でも、visualizerフィールドは必須です。

json

{
  "visualizer": null
}

4. リトライの処理#

決済済みイベント用の安定した event_id を作成し、再試行ごとにそれを再利用します。

レスポンス	対応
HTTP 200	成功です。`duplicate: true`も成功結果として扱われます。
ネットワークエラーまたは HTTP `5xx`	バックオフを使用して再試行し、同じ `event_id` を使い続け。
HTTP 400	リトライ前にリクエストを修正してください。
HTTP 401または403	サーバー認証情報を確認してください。
HTTP 409	停止し、`event_id`が他の注文に使用されていないか確認してください。

成功レスポンスの例：

json

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

5. インテグレーションチェックリスト#

ビジュアライザー使用後にストアフロントがih_visualizerを読み込めることを確認してください。
ih:visualizerリスナーがカートまたはチェックアウトメタデータを更新することを確認してください。
完全なスナップショットが支払い済み注文に到達することを確認します。
サーバーから注文確定テストを提出し、HTTP 200を受け取ることを確認してください。
同じevent_idで同じイベントを再度提出し、duplicate: trueを成功として受け入れてください。
属性なしの注文を"visualizer": nullを使って提出してください。
Client Secretや顧客個人データがブラウザリクエストや送信される注文データに登場しないことを確認してください。