필수 조건
시작하기 전에 다음이 준비되어 있는지 확인하세요:- Vendo 앱이 설치된 Shopify 스토어
- OneSignal 계정 및 앱(웹 플랫폼)
- OneSignal App ID(필수)
- OneSignal REST API Key(주문 동기화 및 사용자 태그 지정과 같은 서버 사이드 이벤트에 필요)
OneSignal 설정
OneSignal 앱 만들기
onesignal.com에 로그인하여 앱을 만들거나 선택합니다. 플랫폼으로 Web을 선택하고 통합 유형으로 Custom Code를 선택합니다.
웹 푸시 설정 구성
OneSignal 앱에서 Settings > Push & In-App > Web Settings으로 이동하거나 웹 푸시 설정 가이드를 따릅니다.사이트 설정
- Site Name: 스토어 이름으로, 기본 알림 제목으로 사용됩니다.
- Site URL: Shopify 스토어의 공개적으로 액세스 가능한 URL(예:
https://yourstore.com).- 사이트의 정확한 출처여야 합니다.
- 고객이
https://your-site.com/과 같은 커스텀 도메인을 통해 사이트에 액세스하는 경우https://your-site.myshopify.com/을 사용하지 마세요.
- Default Icon URL: 알림 프롬프트 및 메시지용 256x256px 정사각형 PNG 또는 JPG 이미지를 업로드합니다. 설정하지 않으면 벨 아이콘이 사용됩니다.
서비스 워커 경로 구성
Shopify는 사이트 루트에서 파일을 제공할 수 없으므로 Vendo가 서비스 워커 파일을 제공하는 위치를 OneSignal에 알려야 합니다.OneSignal에서 Settings > Push & In-App > Web Settings으로 이동하고 Advanced Push Settings까지 스크롤하여 다음과 같이 구성합니다:
| 설정 | 값 |
|---|---|
| Service Worker Path | /apps/vendo/ |
| Service Worker Filename | OneSignalSDKWorker.js |
| Updater Filename | OneSignalSDKWorker.js |
| Service Worker Registration Scope | /apps/vendo/ |
https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js에 필요한 OneSignalSDKWorker.js 파일을 자동으로 제공합니다 — 수동 파일 업로드가 필요하지 않습니다.Updater Filename과 Service Worker Filename은 동일한 파일입니다. OneSignal v16+는 두 가지 목적 모두에 단일 서비스 워커를 사용합니다.
자격 증명 복사
OneSignal에서 Settings > Keys & IDs로 이동하여 App ID와 REST API Key를 복사합니다. Vendo에 입력할 것입니다.
Vendo 설정
OneSignal 통합 추가
Vendo에서 Integrations > Add Integration > OneSignal(또는 Destinations > OneSignal)로 이동합니다.
Vendo 테마 블록 활성화
Vendo 테마 블록은 스토어프론트에 OneSignal SDK를 로드합니다. 이것 없이는 푸시 프롬프트가 나타나지 않고 클라이언트 사이드 추적이 작동하지 않습니다.
- Shopify 관리자에서 Online Store > Themes > Customize로 이동합니다.
- App embeds(왼쪽 사이드바의 퍼즐 조각 아이콘)를 클릭합니다.
- Vendo를 켭니다.
- Save를 클릭합니다.
동기화할 이벤트 선택
Vendo 앱의 OneSignal > Events에서 OneSignal에 보내려는 클라이언트 사이드 및 서버 사이드 이벤트를 활성화합니다. 전체 이벤트 목록은 아래 추적을 참조하세요.
추적
사용자 식별
Vendo는 식별된 사용자 전용 접근 방식을 사용합니다 — 익명 방문자는 OneSignal에서 추적되지 않습니다. 이벤트가 전송되기 전에 사용자는 네 가지 방법 중 하나로 식별되어야 합니다. 이를 통해 중복 사용자를 방지하고 깔끔하고 실행 가능한 데이터를 보장합니다.| 방법 | 작동 방식 | 사용된 식별자 |
|---|---|---|
| 웹 푸시 구독 | 방문자가 푸시 프롬프트에서 “허용”을 클릭합니다. OneSignal이 자동으로 사용자를 생성하고 Vendo가 OneSignal ID를 캡처합니다. | OneSignal ID |
| 뉴스레터 가입 | 방문자가 뉴스레터 또는 이메일 양식을 제출합니다. Vendo가 이메일을 캡처하고 OneSignal.login(email)을 호출합니다. | |
| 고객 로그인 | 고객이 Shopify 계정에 로그인합니다. Vendo가 이를 감지하고 구성된 식별자로 OneSignal.login()을 호출합니다. | Shopify Customer ID 또는 Email |
| 결제 완료 | 고객이 구매를 완료합니다. Vendo가 식별자를 저장하고 OneSignal.login()을 호출합니다. | Shopify Customer ID 또는 Email |
아이덴티티 병합
푸시 구독자(OneSignal ID로 식별)가 나중에 로그인하거나 구매를 완료하면 Vendo는 해당 Shopify Customer ID 또는 이메일로OneSignal.login()을 호출합니다. OneSignal은 푸시 구독을 식별된 사용자에 연결합니다 — 중복 사용자가 생성되지 않습니다. 모든 과거 푸시 구독이 보존되고, 서버 사이드 이벤트(주문, 이행)가 올바른 사용자 프로필에 도달합니다.
고객 태그
Vendo는 세그멘테이션을 위해 고객 속성을 OneSignal의 태그로 동기화합니다. 모든 값은 문자열로 저장됩니다(OneSignal의 네이티브 형식).| 태그 | 설명 |
|---|---|
email | 고객 이메일 |
first_name | 이름 |
last_name | 성 |
total_spent | 누적 지출액 |
order_count | 총 주문 수 |
verified_email | "true" 또는 "false" |
tax_exempt | "true" 또는 "false" |
marketing_state | 마케팅 동의 상태 |
first_order_date | 첫 주문 날짜(ISO 8601) |
last_order_date | 가장 최근 주문 날짜(ISO 8601) |
customer_created_at | 고객 생성 날짜 |
customer_tags | 쉼표로 구분된 Shopify 태그 |
email_marketing_consent | 마케팅 옵트인 상태 |
클라이언트 사이드 이벤트
Vendo는 Shopify Web Pixel을 통해 스토어프론트의 클라이언트 사이드 사용자 지정 이벤트를 추적하여 OneSignal로 보냅니다. 이 이벤트는 사용자가 식별된 후에만 전송됩니다.| 이벤트 | 설명 |
|---|---|
page_viewed | 고객이 페이지를 방문(스토어프론트, 결제 또는 주문 상태) |
product_viewed | 고객이 상품 상세 페이지를 조회 |
collection_viewed | 고객이 상품 컬렉션 페이지를 조회 |
search_submitted | 고객이 스토어프론트 검색 실행 |
product_added_to_cart | 상품이 장바구니에 추가됨 |
product_removed_from_cart | 상품이 장바구니에서 제거됨 |
cart_viewed | 고객이 장바구니 페이지를 조회 |
checkout_started | 고객이 결제 시작 |
checkout_contact_info_submitted | 연락처 정보 단계 제출됨 |
checkout_address_info_submitted | 주소 정보 단계 제출됨 |
checkout_shipping_info_submitted | 배송 방법 선택됨 |
payment_info_submitted | 결제 정보 제출됨 |
checkout_completed | 결제가 성공적으로 완료됨 |
서버 사이드 이벤트
Shopify 커머스 이벤트는 Vendo 파이프라인을 통해 내보내고 OneSignal로 전달됩니다. 항상 Shopify Customer ID를external_id로 사용합니다.
| 이벤트 | 설명 |
|---|---|
received_orders | 새 주문이 생성됨 |
fulfilled_orders | 주문이 이행/배송됨 |
delivered_orders | 주문이 배달됨 |
refunded_orders | 주문이 전액 환불됨 |
partially_refunded_orders | 주문이 부분 환불됨 |
abandoned_checkouts | 결제가 이탈됨 |
공통 이벤트 속성
모든 이벤트에는 다음 속성이 포함됩니다(문자열로):| 속성 | 설명 |
|---|---|
order_id | 표시 주문 식별자 |
shopify_order_id | Shopify 내부 주문 ID |
email | 고객 이메일 |
currency | 주문 통화 |
source | 이벤트 소스 |
version | 통합 버전 |
데이터 동기화 빈도
| 데이터 유형 | 동기화 빈도 |
|---|---|
| 고객 태그 | 4~6시간마다 |
| 주문 이벤트 | 거의 실시간(몇 분 이내) |
| 이탈 장바구니 | 1~2시간마다 |
| 이행 이벤트 | 거의 실시간 |
플랫폼 세부 정보
| 설정 | 값 |
|---|---|
| 동기화 방법 | Vendo를 통한 클라이언트 + 서버 사이드 |
| 아이덴티티 | Shopify Customer ID, Email 또는 OneSignal ID |
| 중복 제거 | 이벤트당 UUID v5 해싱 |
| 배치 크기 | 요청당 1,000개 이벤트 |
| 데이터 형식 | 모든 값을 문자열로 저장 |
사용 사례
이탈 장바구니 복구
abandoned_checkouts 이벤트로 트리거되는 Journey를 만듭니다. 이탈 후 1시간을 기다린 다음 checkout_url 속성을 사용하여 복구 링크가 포함된 푸시 알림을 보냅니다.
주문 상태 업데이트
fulfilled_orders 및 delivered_orders에 대한 Journey를 만들어 주문이 발송되고 도착할 때 추적 정보가 담긴 즉시 푸시 알림을 보냅니다.
VIP 고객 인게이지먼트
total_spent가 임계값보다 큰 세그먼트를 만든 다음 first_name 태그로 개인화된 독점 혜택을 보냅니다.
재참여 캠페인
last_order_date가 90일 이상 된 세그먼트를 만들어 비활성 고객을 타겟팅하고 윈백 캠페인을 보냅니다.
호환 소스
OneSignal은 다음 Vendo 데이터 소스와 함께 작동합니다:| 소스 | 이벤트 | 사용자 태그 | 오디언스 |
|---|---|---|---|
| Shopify | 예 | 예 | 예 |
| Stripe | 예 | 예 | 예 |
| Mixpanel | — | — | 예 |
| Segment | — | — | 예 |
| Amplitude | — | — | 예 |
테스트
서비스 워커 확인
브라우저에서
https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js를 방문합니다. JavaScript 코드가 보여야 합니다. 404가 표시되면 Vendo 앱이 설치되어 있는지 확인하세요.브라우저 DevTools(F12)를 열고 Application > Service Workers로 이동하여 OneSignalSDKWorker.js가 범위 /apps/vendo/로 등록되어 있는지 확인할 수도 있습니다.OneSignal에서 사용자 데이터 확인
Audience > Subscriptions로 이동하여 테스트 구독이 나타나는지 확인합니다. 식별된 사용자에 대해 사용자 태그(이메일, 이름 등)가 동기화되는지 확인합니다.
문제 해결
서비스 워커가 404를 반환
서비스 워커는/apps/vendo/OneSignalSDKWorker.js에 있어야 합니다. 루트 경로(/OneSignalSDKWorker.js)에서 404 오류가 표시되면 OneSignal에 서비스 워커 경로가 구성되지 않은 것입니다 — 서비스 워커 구성 단계를 따르세요. /apps/vendo/ 경로에서 404가 발생하면 Vendo 앱이 설치되어 있고 테마 블록이 활성화되어 있는지 확인하세요.
푸시 프롬프트가 나타나지 않음
App embeds에서 Vendo 테마 블록이 활성화되어 있는지 확인하세요. 브라우저가 알림을 허용하는지 확인하세요(주소 표시줄의 자물쇠 아이콘 클릭). 프롬프트가 이전에 거부되었을 경우를 대비해 시크릿/비공개 창을 시도해 보세요.OneSignal에 태그가 나타나지 않음
태그는 식별된 사용자에게만 동기화됩니다 — 익명 방문자는 추적되지 않습니다. 사용자가 푸시 구독, 로그인, 뉴스레터 가입 또는 결제를 통해 식별되었는지 확인하세요. 초기 태그 동기화는 몇 시간이 걸릴 수 있습니다.이벤트가 트리거되지 않음
Vendo 앱의 OneSignal > Events에서 이벤트가 활성화되어 있는지 확인하세요. 클라이언트 사이드 이벤트는 Shopify Web Pixel이 활성화되어 있고 사용자가 식별되어 있어야 합니다. 서버 사이드 이벤트는 REST API Key가 구성되어 있어야 합니다.알림이 “전달됨”으로 표시되지만 나타나지 않음
통합이 작동하고 있습니다 — 문제는 브라우저 또는 OS 알림 설정에 있습니다. 브라우저의 OS 알림 설정을 확인하고, 방해 금지/집중 모드가 꺼져 있는지 확인하고, 브라우저 수준의 알림 권한을 확인하세요.FAQ
설정 후 고객 식별자를 변경할 수 있나요?
예. Vendo 앱의 Settings > Customer Identifier에서 설정을 업데이트합니다. 기존 사용자가 이미 이전 방법으로 식별된 경우 식별자를 변경하면 별도의 사용자 프로필이 생성될 수 있습니다.Vendo 통합이 모바일 앱을 지원하나요?
Vendo 통합은 Shopify 스토어프론트와 웹 푸시에 초점을 맞춥니다. 모바일 앱도 있는 경우, 사용자 프로필이 일관되게 유지되도록 Vendo에서 선택하는 식별자가 모바일 앱에서 사용하는 식별자와 일치하는지 확인하세요.방문자가 식별되지 않으면 어떻게 되나요?
식별되지 않은 방문자의 이벤트는 OneSignal로 전송되지 않습니다. 방문자가 자신을 식별하면(푸시 구독, 로그인, 뉴스레터 가입 또는 결제 완료), Vendo가 이벤트를 보내기 시작합니다. 이 식별된 사용자 전용 접근 방식은 중복 사용자를 방지하고 깔끔한 데이터를 보장합니다.Vendo가 식별된 사용자 전용 접근 방식을 사용하는 이유는 무엇인가요?
이전 버전은 Shopify의 세션 쿠키를 식별자로 사용하여 익명 방문자를 추적했습니다. 이로 인해 적절하게 병합할 수 없는 중복 OneSignal 사용자가 생성되어 사용자 수 부풀리기와 데이터 단편화가 발생했습니다. 식별된 사용자 전용 접근 방식은 모든 OneSignal 사용자가 실제로 존재하고 실행 가능함을 보장합니다.관련 페이지
Keys & IDs
OneSignal App ID와 REST API 키를 찾습니다.
사용자 지정 이벤트
사용자 행동을 추적하고 Shopify 이벤트를 기반으로 자동화를 트리거합니다.
웹 푸시 설정
Shopify 스토어의 웹 푸시 알림을 설정합니다.
웹 권한 프롬프트
방문자에게 웹 푸시 권한을 요청하는 방법과 시기를 구성합니다.