> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify

> 웹 푸시 알림, 고객 태그, 커머스 이벤트 및 행동 타겟팅을 위해 Vendo 통합을 통해 Shopify를 OneSignal에 연결합니다.

OneSignal은 Vendo와 파트너십을 맺어 원활한 Shopify 통합을 만들었습니다. Vendo는 클릭 한 번으로 Shopify 스토어에 OneSignal SDK를 배포합니다 — 테마 코드를 수동으로 편집할 필요가 없습니다. 고객 태그, 클라이언트 사이드 탐색 이벤트, 서버 사이드 커머스 이벤트를 OneSignal에 동기화하여 실제 행동과 구매 이력을 기반으로 세그먼트를 만들고 푸시 캠페인을 트리거할 수 있습니다.

Vendo 문서는 [Vendo OneSignal Destination](https://docs.vendodata.com/destinations/onesignal/overview)을 참조하세요.

## 필수 조건

시작하기 전에 다음이 준비되어 있는지 확인하세요:

* [Vendo 앱](https://apps.shopify.com/)이 설치된 Shopify 스토어
* OneSignal 계정 및 앱(웹 플랫폼)
* OneSignal **App ID**(필수)
* OneSignal **REST API Key**(주문 동기화 및 사용자 태그 지정과 같은 서버 사이드 이벤트에 필요)

## OneSignal 설정

<Steps>
  <Step title="OneSignal 앱 만들기">
    [onesignal.com](https://onesignal.com)에 로그인하여 앱을 만들거나 선택합니다. 플랫폼으로 **Web**을 선택하고 통합 유형으로 **Custom Code**를 선택합니다.
  </Step>

  <Step title="웹 푸시 설정 구성">
    OneSignal 앱에서 **Settings > Push & In-App > Web Settings**으로 이동하거나 [웹 푸시 설정](./web-push-setup) 가이드를 따릅니다.

    **사이트 설정**

    * **Site Name**: 스토어 이름으로, 기본 알림 제목으로 사용됩니다.
    * **Site URL**: Shopify 스토어의 공개적으로 액세스 가능한 URL(예: `https://yourstore.com`).
      * 사이트의 정확한 [출처](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)여야 합니다.
      * 고객이 `https://your-site.com/`과 같은 커스텀 도메인을 통해 사이트에 액세스하는 경우 `https://your-site.myshopify.com/`을 사용하지 마세요.
    * **Default Icon URL**: 알림 프롬프트 및 메시지용 256x256px 정사각형 PNG 또는 JPG 이미지를 업로드합니다. 설정하지 않으면 벨 아이콘이 사용됩니다.
  </Step>

  <Step title="서비스 워커 경로 구성">
    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/`          |

    <Frame caption="Vendo를 사용하는 Shopify 스토어의 서비스 워커 구성.">
      <img src="https://mintcdn.com/onesignal/N_-d1DtCTRgGPN4l/images/integrations/shopify/vendo-service-worker-configuration.png?fit=max&auto=format&n=N_-d1DtCTRgGPN4l&q=85&s=b7bc1794445e002bd3427c94a6ec6ccf" alt="OneSignal Advanced Push Settings showing service worker paths configured for Vendo" width="3038" height="1108" data-path="images/integrations/shopify/vendo-service-worker-configuration.png" />
    </Frame>

    Vendo는 `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js`에 필요한 `OneSignalSDKWorker.js` 파일을 자동으로 제공합니다 — 수동 파일 업로드가 필요하지 않습니다.

    <Note>
      Updater Filename과 Service Worker Filename은 동일한 파일입니다. OneSignal v16+는 두 가지 목적 모두에 단일 서비스 워커를 사용합니다.
    </Note>
  </Step>

  <Step title="자격 증명 복사">
    OneSignal에서 [**Settings > Keys & IDs**](./keys-and-ids)로 이동하여 **App ID**와 **REST API Key**를 복사합니다. Vendo에 입력할 것입니다.
  </Step>
</Steps>

## Vendo 설정

<Steps>
  <Step title="Vendo 앱 설치">
    Shopify App Store에서 Vendo 앱을 설치합니다.
  </Step>

  <Step title="OneSignal 통합 추가">
    Vendo에서 **Integrations > Add Integration > OneSignal**(또는 **Destinations > OneSignal**)로 이동합니다.

    <Frame caption="Vendo에서 OneSignal 통합 추가.">
      <img src="https://mintcdn.com/onesignal/PoskQI_qr0DD8jDV/images/integrations/shopify/vendo-onesignal-integrations.png?fit=max&auto=format&n=PoskQI_qr0DD8jDV&q=85&s=13acfaf4e6b01f77535f1a1386c4212d" alt="Vendo Integrations page showing the OneSignal integration option" width="2520" height="1756" data-path="images/integrations/shopify/vendo-onesignal-integrations.png" />
    </Frame>
  </Step>

  <Step title="OneSignal 자격 증명 입력">
    이전 섹션의 OneSignal **App ID**와 **REST API Key**를 입력한 다음 **Save**를 클릭합니다.
  </Step>

  <Step title="Vendo 테마 블록 활성화">
    Vendo 테마 블록은 스토어프론트에 OneSignal SDK를 로드합니다. 이것 없이는 푸시 프롬프트가 나타나지 않고 클라이언트 사이드 추적이 작동하지 않습니다.

    1. Shopify 관리자에서 **Online Store > Themes > Customize**로 이동합니다.
    2. **App embeds**(왼쪽 사이드바의 퍼즐 조각 아이콘)를 클릭합니다.
    3. **Vendo**를 켭니다.
    4. **Save**를 클릭합니다.

    테마 블록은 SDK 초기화, 서비스 워커 등록, 푸시 프롬프트 표시, 사용자 식별(푸시 구독, 로그인, 뉴스레터 가입) 및 태그 동기화를 처리합니다.
  </Step>

  <Step title="동기화할 이벤트 선택">
    Vendo 앱의 **OneSignal > Events**에서 OneSignal에 보내려는 클라이언트 사이드 및 서버 사이드 이벤트를 활성화합니다. 전체 이벤트 목록은 아래 [추적](#tracking)을 참조하세요.
  </Step>

  <Step title="히스토리 데이터 동기화(선택 사항)">
    Vendo는 기존 고객과 최근 주문 내역을 OneSignal에 역채울 수 있습니다. 자격 증명을 저장한 후 백그라운드에서 자동으로 실행됩니다.

    <Frame caption="Vendo의 히스토리 데이터 동기화 옵션.">
      <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-historical-data.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=4eb61a384a7ac3f4596661348f98ac48" alt="Vendo historical data settings showing sync options for Shopify data" width="1724" height="762" data-path="images/integrations/shopify/vendo-historical-data.png" />
    </Frame>
  </Step>
</Steps>

## 추적

### 사용자 식별

Vendo는 **식별된 사용자 전용** 접근 방식을 사용합니다 — 익명 방문자는 OneSignal에서 추적되지 않습니다. 이벤트가 전송되기 전에 사용자는 네 가지 방법 중 하나로 식별되어야 합니다. 이를 통해 중복 사용자를 방지하고 깔끔하고 실행 가능한 데이터를 보장합니다.

| 방법          | 작동 방식                                                                             | 사용된 식별자                      |
| ----------- | --------------------------------------------------------------------------------- | ---------------------------- |
| **웹 푸시 구독** | 방문자가 푸시 프롬프트에서 "허용"을 클릭합니다. OneSignal이 자동으로 사용자를 생성하고 Vendo가 OneSignal ID를 캡처합니다. | OneSignal ID                 |
| **뉴스레터 가입** | 방문자가 뉴스레터 또는 이메일 양식을 제출합니다. Vendo가 이메일을 캡처하고 `OneSignal.login(email)`을 호출합니다.     | Email                        |
| **고객 로그인**  | 고객이 Shopify 계정에 로그인합니다. Vendo가 이를 감지하고 구성된 식별자로 `OneSignal.login()`을 호출합니다.       | Shopify Customer ID 또는 Email |
| **결제 완료**   | 고객이 구매를 완료합니다. Vendo가 식별자를 저장하고 `OneSignal.login()`을 호출합니다.                       | Shopify Customer ID 또는 Email |

<Warning>
  모바일 앱이나 서드파티 연결이 있는 경우, 사용자 프로필이 플랫폼 전반에 걸쳐 일관되게 유지되도록 다른 도구와 일치하는 식별자(Shopify Customer ID 대 Email)를 선택하세요. Vendo 앱의 **Settings > Customer Identifier**에서 구성합니다.
</Warning>

#### 아이덴티티 병합

푸시 구독자(OneSignal ID로 식별)가 나중에 로그인하거나 구매를 완료하면 Vendo는 해당 Shopify Customer ID 또는 이메일로 `OneSignal.login()`을 호출합니다. OneSignal은 푸시 구독을 식별된 사용자에 연결합니다 — 중복 사용자가 생성되지 않습니다. 모든 과거 푸시 구독이 보존되고, 서버 사이드 이벤트(주문, 이행)가 올바른 사용자 프로필에 도달합니다.

### 고객 태그

Vendo는 세그멘테이션을 위해 고객 속성을 OneSignal의 [태그](./add-user-data-tags)로 동기화합니다. 모든 값은 문자열로 저장됩니다(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을 통해 스토어프론트의 클라이언트 사이드 [사용자 지정 이벤트](./custom-events)를 추적하여 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`               | 결제가 성공적으로 완료됨                    |

<Frame caption="Vendo의 클라이언트 사이드 이벤트 구성.">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-client-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c94b99465b8c200ebb1bb475e492f8a1" alt="Vendo client-side events settings showing available custom events" width="865" height="726" data-path="images/integrations/shopify/vendo-client-side-events.png" />
</Frame>

### 서버 사이드 이벤트

Shopify 커머스 이벤트는 Vendo 파이프라인을 통해 내보내고 OneSignal로 전달됩니다. 항상 Shopify Customer ID를 `external_id`로 사용합니다.

| 이벤트                         | 설명         |
| --------------------------- | ---------- |
| `received_orders`           | 새 주문이 생성됨  |
| `fulfilled_orders`          | 주문이 이행/배송됨 |
| `delivered_orders`          | 주문이 배달됨    |
| `refunded_orders`           | 주문이 전액 환불됨 |
| `partially_refunded_orders` | 주문이 부분 환불됨 |
| `abandoned_checkouts`       | 결제가 이탈됨    |

<Frame caption="Vendo의 서버 사이드 이벤트 구성.">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-server-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c9bed30c26b0bec3b8a53eb8cde8098d" alt="Vendo server-side events settings showing available Shopify webhook events" width="865" height="394" data-path="images/integrations/shopify/vendo-server-side-events.png" />
</Frame>

### 공통 이벤트 속성

모든 이벤트에는 다음 속성이 포함됩니다(문자열로):

| 속성                 | 설명               |
| ------------------ | ---------------- |
| `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](./journeys-overview)를 만듭니다. 이탈 후 1시간을 기다린 다음 `checkout_url` 속성을 사용하여 복구 링크가 포함된 푸시 알림을 보냅니다.

### 주문 상태 업데이트

`fulfilled_orders` 및 `delivered_orders`에 대한 Journey를 만들어 주문이 발송되고 도착할 때 추적 정보가 담긴 즉시 푸시 알림을 보냅니다.

### VIP 고객 인게이지먼트

`total_spent`가 임계값보다 큰 [세그먼트](./segmentation)를 만든 다음 `first_name` 태그로 개인화된 독점 혜택을 보냅니다.

### 재참여 캠페인

`last_order_date`가 90일 이상 된 세그먼트를 만들어 비활성 고객을 타겟팅하고 윈백 캠페인을 보냅니다.

## 호환 소스

OneSignal은 다음 Vendo 데이터 소스와 함께 작동합니다:

| 소스        | 이벤트 | 사용자 태그 | 오디언스 |
| --------- | --- | ------ | ---- |
| Shopify   | 예   | 예      | 예    |
| Stripe    | 예   | 예      | 예    |
| Mixpanel  | —   | —      | 예    |
| Segment   | —   | —      | 예    |
| Amplitude | —   | —      | 예    |

이벤트와 사용자 태그는 Shopify 또는 Stripe를 데이터 소스로 필요로 합니다. 오디언스 세그먼트는 BigQuery 데이터셋의 모든 소스 데이터로 구축할 수 있습니다.

***

## 테스트

<Steps>
  <Step title="서비스 워커 확인">
    브라우저에서 `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js`를 방문합니다. JavaScript 코드가 보여야 합니다. 404가 표시되면 Vendo 앱이 설치되어 있는지 확인하세요.

    브라우저 DevTools(**F12**)를 열고 **Application > Service Workers**로 이동하여 `OneSignalSDKWorker.js`가 범위 `/apps/vendo/`로 등록되어 있는지 확인할 수도 있습니다.
  </Step>

  <Step title="푸시 프롬프트 테스트">
    시크릿/비공개 창에서 스토어프론트를 엽니다. OneSignal 알림 권한 프롬프트가 표시되어야 합니다. **허용**을 클릭하여 구독합니다.
  </Step>

  <Step title="테스트 알림 보내기">
    OneSignal 대시보드에서 **Messages > Push > New Message**로 이동합니다. 구독자에게 테스트 알림을 보내고 나타나는지 확인합니다.
  </Step>

  <Step title="OneSignal에서 사용자 데이터 확인">
    **Audience > Subscriptions**로 이동하여 테스트 구독이 나타나는지 확인합니다. 식별된 사용자에 대해 사용자 태그(이메일, 이름 등)가 동기화되는지 확인합니다.
  </Step>

  <Step title="테스트 이벤트 트리거">
    스토어에서 상품을 탐색하거나 테스트 결제를 완료합니다. OneSignal 대시보드의 사용자 활동에 이벤트가 나타나는지 확인합니다.
  </Step>
</Steps>

***

## 문제 해결

### 서비스 워커가 404를 반환

서비스 워커는 `/apps/vendo/OneSignalSDKWorker.js`에 있어야 합니다. 루트 경로(`/OneSignalSDKWorker.js`)에서 404 오류가 표시되면 OneSignal에 서비스 워커 경로가 구성되지 않은 것입니다 — [서비스 워커 구성 단계](#configure-the-service-worker-path)를 따르세요. `/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 사용자가 실제로 존재하고 실행 가능함을 보장합니다.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    OneSignal App ID와 REST API 키를 찾습니다.
  </Card>

  <Card title="사용자 지정 이벤트" icon="bolt" href="./custom-events">
    사용자 행동을 추적하고 Shopify 이벤트를 기반으로 자동화를 트리거합니다.
  </Card>

  <Card title="웹 푸시 설정" icon="globe" href="./web-push-setup">
    Shopify 스토어의 웹 푸시 알림을 설정합니다.
  </Card>

  <Card title="웹 권한 프롬프트" icon="bell" href="./permission-requests">
    방문자에게 웹 푸시 권한을 요청하는 방법과 시기를 구성합니다.
  </Card>
</Columns>