Shopify 상품과 구매를 표시하세요.

Social Stream Ninja의 Shopify

이미지, 가격, 읽기 쉬운 링크, QR 코드로 공개 상품을 홍보하세요. 서명된 결제 완료 주문 알림을 다음 유형으로 받습니다: purchase 알림으로 활동 피드, 다중 알림, 이벤트 흐름에서 받습니다. 상품 홍보는 결제 알림과 독립적으로 작동합니다.

구매 연결 · 상품 가져오기 · OBS 오버레이 · 안전하게 테스트 · 제한 및 문제 해결

사용 가능 여부: 자동 알림에는 SSN API에 Shopify 수신기가 배포되고 활성화되어 있어야 합니다. 사용할 수 없으면 Save setup이 오류를 표시하고 Shopify를 활성화하지 않습니다. 공개 상품 가져오기와 수동 홍보는 독립적으로 작동합니다. 이 가이드는 통합 코드를 설명하며 실제 서비스 검증을 완료했다고 말하려면 실제 판매자 테스트가 여전히 필요합니다.

결제 완료 구매 연결

1. Shopify에서 다음을 여세요: Settings → Notifications → Webhooks를 여세요. 수동으로 만든 웹훅에 표시된 서명 비밀 키를 찾으세요. Storefront 토큰과는 다릅니다.
2. SSN에서 다음을 여세요: 수익화 → Shopify 구매 → 설정 (Monetization → Shopify purchases → Setup)를 여세요. 영구 your-store.myshopify.com 도메인과 웹훅 서명 비밀 키를 입력하세요. Shopify 구매를 활성화한 뒤 다음을 클릭하세요: 설정 저장.
3. 클릭: 수신기 URL 복사 (Copy receiver URL)을 클릭하세요. Shopify에서 웹훅을 만들고 이벤트를 주문 결제 (Order payment), 형식은 JSON, 해당 수신기 URL을 지정하세요. 지원되는 안정적 웹훅 API 버전을 선택하세요. 이 통합은 2026-07 주문 규약을 기준으로 개발되었습니다.
4. Shopify 웹훅을 저장하세요. 구매를 처리하려면 SSN을 켜 두세요. 수신기는 주문 데이터를 받기 전에 원본 본문의 HMAC과 스토어 일치 여부를 검증합니다.

서명 비밀 키는 SSN 수신기에서 암호화되며 저장 후 입력란에서 지워집니다. 별도의 비공개 읽기 키는 이 장치에 남습니다. 두 키 모두 OBS 링크나 시청자 QR 코드에 포함되지 않습니다. Shopify는 전용 수신기를 사용하므로 이전 원격 API 제어 스위치는 필요하지 않습니다.

URL이 생성되었다는 것은 설정이 저장되었다는 뜻이지 Shopify가 무언가를 전달했다는 뜻은 아닙니다. 상태는 대기, 검증된 테스트, 건너뛴 이벤트, 수신한 구매를 구분합니다. 스토어를 변경하려면 먼저 Disconnect가 필요합니다. Shopify를 끄면 로컬 처리가 일시 중지되고 Disconnect는 수신기와 대기 중인 이벤트를 삭제합니다. 연결 해제 시 해당 Shopify 웹훅도 제거하세요.

Shopify: 웹훅 수동 생성 · Shopify: 전달 검증

공개 상품 가져오기

1. 입력할 값: myshopify.com 도메인을 Shopify 설정에 입력하세요. 상품을 가져오는 데 구매 알림을 활성화하거나 서명 비밀 키를 입력할 필요는 없습니다.
2. 펼칠 항목: 상품 가져오기를 펼치고 공개 상품 URL을 붙여 넣은 뒤 다음을 클릭하세요: 상품 세부 정보 불러오기.
3. 토큰 없이 상품에 접근할 수 없다면 다음을 제공하세요: 공개 Storefront 토큰을 제공하세요. Shopify의 Headless 채널에서 만들 수 있습니다. 해당 스토어프런트와 Online Store에 상품을 게시하세요. Admin API 토큰이나 비공개 Storefront 토큰을 붙여 넣지 마세요.
4. SSN은 기존의 상품 및 후원 링크 편집기를 Shopify가 반환한 제목, 이미지, 가격, 정식 공개 링크로 엽니다. 검토한 뒤 다음을 클릭하세요: 상품 또는 링크 추가을 클릭하고 카탈로그를 활성화한 뒤 설정 저장.

가져오기는 Storefront API로 한 번에 상품 하나를 읽습니다. 토큰은 선택 사항이며 해당 요청에만 사용되고 이후 지워집니다. Shopify가 반환한 정식 Online Store URL이 공개 링크가 되며 사용자 지정 도메인이 반환되면 그것도 포함됩니다. 사용할 수 없는 상품과 공개 Online Store 링크가 없는 상품은 제외됩니다.

상품 옵션의 최저 가격과 최고 가격이 같을 때만 가격이 입력됩니다. 다르면 비워 두며, 상품을 정확히 설명하는 경우에만 특정 가격을 직접 선택하세요. 가져온 정보는 한 시점의 정보이며 재고나 가격을 계속 동기화하지 않습니다. 스토어가 바뀌면 검토하세요. 언제든 수동 상품 입력을 대신 사용할 수 있습니다.

Shopify Storefront 인증 · 상품 쿼리 · Headless로 공개 토큰 만들기

기존 오버레이 사용

다음 항목 아래에서: 다음용 오버레이 링크:에서 다음을 선택하세요: 상품 및 후원 링크. 사용: 상품 쇼케이스만 (Product showcase only) 는 이미지, 가격, QR 코드에, 후원 카드만 (Support card only) 는 작게 상시 또는 주기적으로 표시할 상점 링크에, 또는 활동 알림만 (Activity alerts only) 는 구매에 사용하세요. 원하는 각 OBS 링크를 별도 브라우저 소스에 복사하고 800 × 600으로 시작하세요.

선택적 알림 소스 필터를 다음으로 설정하세요: shopify 로 설정하면 일반 수익화 오버레이에 Shopify 활동만 표시합니다. 해당 일반 화면에는 Products & support links를 활성화하세요. 기존 다중 알림과 활동 피드는 상품 카탈로그와 독립적으로 Shopify 구매를 받습니다.

상품 카드는 공개 상품 페이지로 연결됩니다. 다음을 사용하세요: 공개 링크 복사 로 클릭 가능한 주소를 채팅에 공유하고 최종 방송 크기에서 휴대폰으로 QR 코드를 시험하세요. 구매 알림은 관련 없는 순환 상품의 QR 코드나 이미지를 가져오지 않습니다. 주문 웹훅은 신뢰할 수 있는 상품 이미지 URL을 제공하지 않으므로 구매 알림은 텍스트를 사용하고 가져온 홍보 카드는 이미지를 표시할 수 있습니다.

이벤트 흐름에서는 Event Type으로 다음을 선택하세요: purchase 를 선택하고 소스/유형 필터를 다음으로 설정하세요: shopify로 설정하세요. 비교할 값: meta.commerce.orderTotal 를 주문 금액 규칙에 비교하고 다음을 확인하세요: meta.commerce.currency 를 금액 비교 전에 확인하세요. 이는 구매이며 다음 필드는 hasDonation 또는 donoValue 전송되지 않으며 후원 목표도 증가하지 않습니다. Gift라고 표시한 홍보 카드가 주문 이벤트 분류를 바꾸지는 않습니다. 다른 사람에게 배송한다고 크리에이터에게 주는 선물인 것은 아닙니다.

안전한 미리 보기 및 테스트

샘플 미리 보기 (Preview sample) 는 세션 연결 없이 격리된 샘플 오버레이를 엽니다. 이벤트 흐름을 실행하거나 합계를 바꾸거나 결제를 검증하지 않습니다.

Shopify 주문에 다음이 명시된 경우: test: true 수신을 확인하고 수신기 상태에 테스트로 표시하며 구매 알림이나 동작은 실행하지 않습니다. 테스트 플래그 누락, 미결제/부분 결제 주문, 취소된 주문, 합계 0, 오래되거나 잘못된 타임스탬프도 건너뜁니다. 전체 과정 테스트에는 개발 스토어를 사용하세요. 신뢰할 수 있는 테스트 플래그가 없는 관리자 샘플을 활성 보상 흐름에 보내면 안 됩니다. 모양 확인에는 SSN 미리 보기가 안전합니다.

스토어 없이 검증한 내용

격리된 테스트에서는 서명된 유니코드 JSON을 이용한 실제 HTTP 전달, 변조된 서명, 중복 전달, 테스트 주문 격리, 통화 정밀도, 과도하게 큰 요청, 비공개 고객 데이터 제거, 실제 SSApp 런타임을 통한 오프라인 복구를 확인합니다. 이 검증은 주문을 넣지 않으며 판매자 계정이 필요하지 않습니다.

운영용 Shopify 수신기는 실제 스토어 전달 테스트를 기다리는 동안 비활성화되어 있습니다. 수동 상품 홍보는 독립적으로 사용할 수 있습니다. Shopify CLI 샘플 웹훅은 페이로드 처리 테스트에 도움이 되지만 구독이나 재시도를 검증하지 않으며 앱 자격 증명이 필요합니다. 참고: Shopify CLI 웹훅 테스트 제한.

전달 제한 및 문제 해결

• 수신기를 사용할 수 없음: SSN API 운영자가 Shopify 수신기를 배포하고 활성화해야 합니다. 참고: 서버 설정를 참고하세요. 서명되지 않은 이전 세션 웹훅 URL을 대신 사용하지 마세요.
• 이벤트 대기 중: Order payment, JSON, 정확한 수신기 URL, 일치하는 영구 스토어 도메인, 해당 웹훅의 서명 비밀 키를 확인하세요. 사용자 지정 앱 웹훅은 수동 Notifications 비밀 키가 아닌 해당 앱의 서명 비밀 키를 사용합니다.
• 서명된 이벤트를 건너뜀: 이 통합에는 금액이 양수이고 전액 결제된 주문, test: false 및 서명된 본문의 updated_at 이 최근 7일 이내여야 합니다(미래 시각은 5분까지 허용). 주문 생성, 이행 또는 재고로 결제를 추정하지 않습니다.
• SSN이 오프라인이었음: 수락한 이벤트는 최대 7일간 대기열에 보관됩니다. SSN을 다시 시작하면 재개됩니다. 수신기를 다시 시작해도 상태와 대기 작업은 유지됩니다. 서비스의 저장 용량은 제한되어 있으며 작업을 영구 대기열에 넣을 수 없으면 Shopify에 재시도를 요청합니다.
• 중복: 수신기는 Shopify 전달 ID가 달라도 스토어/주문별로 중복을 제거합니다. 중복 제거 기록은 7일간 유지됩니다. SSN은 수신 확인 전에 처리한 ID를 영구 저장합니다. 외부 동작과 저장 사이에 충돌하면 동작이 반복될 수 있으므로 영향이 큰 자동화에는 자체 멱등성 보호를 사용하세요.
• 구매자 이름이 없음: 의도된 동작입니다. SSN은 고객 이름, 이메일, 주소, 주문 메모, 주문 항목의 사용자 지정 속성, 결제 URL, 원시 주문 ID를 제외합니다. 공개 상품 제목은 일반 텍스트로 유지됩니다.
• 환불 또는 주문 변경: 이것은 회계나 주문 이행 시스템이 아닌 실시간 알림 피드입니다. 환불, 취소, 합계 수정은 이전 알림을 되돌리지 않습니다. 주문 기록 대조나 자동 상품 제거는 포함되지 않습니다.

다음을 참조하세요: Shopify 이벤트 규약 그리고 공용 상품 및 QR 가이드.