Visualizer 귀속을 결제된 주문에 연결#
Visualizer SDK가 게시한 귀속 스냅샷을 캡처하여 고객 장바구니 또는 체크아웃과 함께 보관하고, 최종 결제된 주문을 서버에서 보고하십시오.
SDK는 장바구니를 수정하거나 주문을 자동으로 보고하지 않습니다. 귀하의 통합은 다음을 수행해야 합니다:
- 스토어프론트에서 최신 스냅샷 캡처하기
- 완전한 스냅샷을 장바구니와 주문에 함께 보관하기
- 결제된 주문을 신뢰할 수 있는 서버에서 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)
}
상업 플랫폼의 장바구니 속성, 체크아웃 메타데이터 또는 서버 측 세션 API와 함께 saveAttributionWithCart을 구현합니다.
스냅샷 필드는 다음과 같습니다:
{
"visitor_id": "anonymous-visitor-id",
"session_id": "visualizer-session-id",
"categories": ["wall", "furniture"],
"last_used_at": "2026-09-10T12:34:56.000Z"
}
완전한 스냅샷을 함께 저장하고 교체하세요. 필드명을 변경하거나, 값의 일부를 복사하거나, 수정하지 마세요. 쿠키에서 읽은 데이터는 신뢰할 수 없는 것으로 간주하며, 이 형태를 갖춘 완전한 객체가 아닌 경우 폐기하세요.
체크아웃이 다른 호스트명을 사용하거나 외부 플랫폼인 경우, 고객이 스토어프론트 페이지를 떠나기 전에 스냅샷을 장바구니 또는 서버 측 세션에 복사하십시오.
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. 결제된 주문 보고#
백엔드 또는 결제된 주문 웹훅 처리기에서 이 엔드포인트를 호출합니다. 브라우저 JavaScript에서는 절대 호출하지 마십시오.
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을 포함하지 마십시오.
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 필드는 여전히 필요합니다.
{
"visualizer": null
}
4. 재시도 처리#
지불된 주문 이벤트에 대한 안정적인 event_id를 생성하고 모든 재시도 시 이를 재사용하세요.
| 응답 | 실행 조치 |
|---|---|
| HTTP 200 | 성공. duplicate: true 또한 성공 결과입니다. |
네트워크 오류 또는 HTTP 5xx | 대기 시간을 두고 동일한 event_id로 재시도하세요. |
| HTTP 400 | 재시도하기 전에 요청을 수정합니다. |
| HTTP 401 또는 403 | 서버 자격 증명을 확인합니다. |
| HTTP 409 | 중단하고 event_id이 다른 주문에 사용되었는지 확인합니다. |
성공 응답 예시
{
"accepted": true,
"duplicate": false,
"visualizer_assisted": true
}
5. 통합 체크리스트#
- Visualizer 사용 후 스토어프론트가
ih_visualizer를 읽을 수 있는지 확인합니다. ih:visualizer리스너가 장바구니 또는 체크아웃 메타데이터를 업데이트하는지 확인합니다.- 완전한 스냅샷이 결제 완료된 주문에 도달하는지 확인하세요.
- 서버에서 유료 테스트 주문을 제출하고 HTTP 200을 기대합니다.
- 동일한
event_id로 같은 이벤트를 다시 제출하고duplicate: true을 성공으로 받아들이기 "visualizer": null을 사용하여 귀속 없는 주문을 제출합니다.- Client Secret와 고객 개인 데이터가 브라우저 요청이나 제출된 주문 데이터에 전혀 나타나지 않는지 확인합니다.