> ## 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.

# Amplitude

> 행동 기반 코호트를 동기화하고, 메시지 이벤트를 추적하며, 푸시, 이메일, SMS 및 인앱 채널에서 사용자를 타겟팅하기 위해 OneSignal과 Amplitude를 통합합니다.

OneSignal을 [Amplitude](https://amplitude.com)와 통합하여 푸시, 인앱, 이메일 및 SMS에서 실시간 행동 기반 타겟팅을 활성화합니다. 이 앱 수준 통합은 세 가지 데이터 흐름을 지원합니다:

* **메시지 이벤트 → Amplitude**: 모든 채널에서 전달, 클릭, 실패 등을 추적합니다.
* **사용자 지정 이벤트 → OneSignal**: Amplitude 이벤트를 OneSignal로 전송하여 Journeys 또는 세그먼트를 트리거합니다.
* **코호트 → OneSignal**: 행동 기반 Amplitude 코호트를 OneSignal의 타겟팅 필터로 동기화합니다.

***

## 요구 사항

* [Amplitude 계정](https://amplitude.com/pricing)
* [OneSignal 유료 플랜](https://onesignal.com/pricing)
* [사용자](./users) 및 External ID가 설정된 OneSignal 앱.

<Warning>
  이 통합은 사용자를 생성하지 않습니다. Amplitude의 사용자를 식별자 일치를 통해 OneSignal의 기존 사용자에 매핑합니다.
</Warning>

***

## 설정

### OneSignal에 Amplitude 추가 (아웃바운드)

OneSignal 메시지 이벤트를 Amplitude 프로젝트로 전송합니다.

1. OneSignal에서 **데이터 > 통합 > 카탈로그**로 이동하여 **Amplitude**를 선택합니다.
2. **설정**을 클릭한 후 **아웃바운드** 탭을 엽니다.
3. Amplitude API 토큰을 입력하고, 전송할 메시지 이벤트를 선택한 후 **저장**을 클릭합니다.

#### Amplitude에서

1. 프로젝트 API 키를 찾아 OneSignal에 복사하여 붙여넣습니다.
2. Amplitude의 EU 서버를 사용하는 경우 **Amplitude의 EU Residency 엔드포인트로만 이벤트 전송**을 체크합니다. Amplitude URL로 확인할 수 있습니다. `eu.amplitude.com`이 표시되면 Amplitude의 EU 서버를 사용하고 있는 것입니다.

### Amplitude에 OneSignal 추가 (인바운드)

Amplitude Destinations에서 **OneSignal**을 검색합니다.

<Frame caption="Amplitude에서 OneSignal 대상 추가">
  <img src="https://mintcdn.com/onesignal/TbJ7SH8gAntayRJq/images/integrations/amplitude-destination.png?fit=max&auto=format&n=TbJ7SH8gAntayRJq&q=85&s=fe7b7967e5e219556a6356915b0238fa" alt="Amplitude destinations catalog with OneSignal selected" width="2288" height="1168" data-path="images/integrations/amplitude-destination.png" />
</Frame>

Amplitude는 카탈로그에서 두 가지 OneSignal 대상 유형을 제공합니다:

* **Cohorts**: Amplitude에서 OneSignal로 코호트를 동기화합니다.
* **Events User Properties**: Amplitude에서 OneSignal로 사용자 지정 이벤트를 전송합니다.

<Note>
  코호트 동기화와 사용자 지정 이벤트를 모두 사용할 계획이라면 두 OneSignal 대상을 모두 추가하세요. 각 대상은 Amplitude에서 개별적으로 구성되므로 각각에 대해 OneSignal 자격 증명을 입력해야 합니다.
</Note>

### User ID 매핑

OneSignal의 \*\*[External ID](./users)\*\*는 선택한 Amplitude 사용자 속성(예: `user_id`)과 일치해야 합니다. 이 속성이 두 시스템 모두에 채워져 있는지 확인하세요 — 코호트 동기화 및 이벤트 추적은 정확한 일치에 의존합니다.

#### 추가 속성

OneSignal의 [사용자 지정 이벤트](./custom-events)에 첨부될 추가 속성을 포함할 수 있습니다. 이는 조건부 이벤트 처리에 유용합니다.

<Check>
  완료되면 **저장**을 클릭합니다. 이제 Amplitude에서 OneSignal로 코호트 및 사용자 지정 이벤트를 내보내고 OneSignal에서 Amplitude로 메시지 이벤트를 수집할 수 있습니다.
</Check>

***

## 사용자 지정 이벤트 테스트

1. Amplitude > OneSignal Events Destination에서 Test Connection 버튼을 클릭합니다.

<Frame caption="Amplitude > OneSignal Events 대상">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-test-connection.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=8202b1ee8513456d78777425db4a7753" alt="Amplitude Events destination page with Test Connection button highlighted" width="1970" height="1160" data-path="images/integrations/amplitude-test-connection.png" />
</Frame>

2. 페이로드의 `"user_id"`가 OneSignal 앱의 기존 사용자의 External ID로 설정되어 있는지 확인합니다.
3. **Send Test Event** 버튼을 클릭합니다.
4. Response 상자는 비어 있어야 하며 `"OneSignal has successfully received test event."`라는 메시지가 표시되어야 합니다.

<Frame caption="응답 예제">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-test-connection-response.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=14b5824d639a748252a36315bc491383" alt="Successful test event response showing confirmation message" width="2438" height="1500" data-path="images/integrations/amplitude-test-connection-response.png" />
</Frame>

5. OneSignal에서 **데이터 > 사용자 지정 이벤트**로 이동하여 목록에 테스트 이벤트가 표시되는지 확인합니다.

<Frame caption="OneSignal의 사용자 지정 이벤트">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/onesignal-custom-event.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=18c287884737e192fde2da0e28d65676" alt="OneSignal Custom Events list showing the test event from Amplitude" width="2736" height="1032" data-path="images/integrations/onesignal-custom-event.png" />
</Frame>

<Warning>
  테스트가 실패하거나 이벤트가 OneSignal에 표시되지 않으면 Amplitude에 OneSignal 앱 ID 및 REST API 키가 올바르게 입력되어 있는지, 앱이 [사용자 지정 이벤트](./custom-events)에 대해 구성되어 있는지, 그리고 `"user_id"`가 OneSignal 앱의 기존 사용자 External ID와 일치하는지 확인하세요.
</Warning>

## Amplitude 코호트를 OneSignal로 내보내기

위에서 구성한 일치하는 External ID를 사용하여 Amplitude 코호트를 OneSignal에 동기화합니다. 내보내기는 **사용자를 생성하지 않습니다** — 각 사용자는 이미 OneSignal에 존재해야 합니다.

1. Amplitude에서 코호트를 생성합니다. [Amplitude의 코호트 문서](https://amplitude.com/docs/analytics/behavioral-cohorts)를 참조하세요.
2. **동기화**를 클릭하고 **OneSignal**을 대상으로 선택합니다.
3. 동기화 빈도를 선택합니다.

<Frame caption="Amplitude 코호트의 OneSignal 동기화 주기 설정">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-sync-cadence.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=9ba4b69273f73ccdd1f095c2a3ede63c" alt="Amplitude cohort sync settings showing frequency options for OneSignal destination" width="602" height="499" data-path="images/integrations/amplitude-sync-cadence.png" />
</Frame>

### OneSignal 세그먼트 생성

동기화된 코호트는 **Amplitude 세그먼트 필터**로 나타납니다. 다음 경우 OneSignal이 코호트에 대한 세그먼트를 자동으로 생성합니다:

* Amplitude 코호트의 사용자가 일치하는 External ID로 OneSignal에도 존재합니다.
* OneSignal의 세그먼트 제한을 초과하지 않아야 합니다.

<Frame caption="Amplitude 코호트에서 세그먼트 생성">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/526a986-Screenshot_2023-09-22_at_7.01.09_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=e5de1d6896a542a980b9840a05200586" alt="OneSignal Segment builder using Amplitude Cohort filter" width="1622" height="878" data-path="images/docs/526a986-Screenshot_2023-09-22_at_7.01.09_PM.png" />
</Frame>

***

## Amplitude에서 메시지 이벤트 추적

OneSignal은 다음 메시지 이벤트를 실시간으로 Amplitude에 전송합니다. **데이터 > 통합 > Amplitude > 아웃바운드**에서 전송할 이벤트를 선택합니다.

| Message Event Kind (OneSignal) | Message Event Name (Amplitude)                                | Event Description                                                                      |
| ------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Push Sent                      | \[Onesignal] Push Delivered                                   | Push notification successfully sent.                                                   |
| Push Received                  | \[Onesignal] Push confirmed receipt                           | Push notification successfully received                                                |
| Push Clicked                   | \[Onesignal] Push Clicked                                     | Push notification touched on device                                                    |
| Push Failed                    | \[Onesignal] Push Failed                                      | Push failed to be sent. Check the failed message report in OneSignal.                  |
| Push Unsubscribed              | \[Onesignal] Push Unsubscribed                                | The [Subscription](./subscriptions) unsubscribed from push.                            |
| In-App Impression              | \[Onesignal] IAM Displayed                                    | In-App Message successfully displayed on device                                        |
| In-App Clicked                 | \[Onesignal] IAM Clicked                                      | In-App Message clicked on device                                                       |
| In-App Page Displayed          | \[Onesignal] IAM Page Displayed                               | In-App Message page is displayed                                                       |
| Email Sent                     | \[Onesignal] Email Delivered                                  | Email successfully sent                                                                |
| Email Received                 | \[Onesignal] Email confirmed receipt                          | Email received by recipient                                                            |
| Email Opened                   | \[Onesignal] Email Opened                                     | Email opened by recipient                                                              |
| Email Link Clicked             | \[Onesignal] Email Clicked                                    | Email link clicked on                                                                  |
| Email Unsubscribed             | \[Onesignal] Email Unsubscribed                               | Email unsubscribed by recipient                                                        |
| Email Reported As Spam         | \[Onesignal] Email Reported as SPAM                           | Email reported as spam by recipient                                                    |
| Email Bounced                  | \[Onesignal] Email Hard bounced                               | Email returned to sender due to permanent error                                        |
| Email Failed                   | \[Onesignal] Email Failed delivery                            | Could not deliver the email to the recipient's inbox                                   |
| Email Suppressed               | \[Onesignal] Email Not delivering to suppressed email address | Email not delivered as the recipient had suppressed the email address it was sent from |
| SMS Sent                       | \[Onesignal] SMS Delivered                                    | SMS sent to recipient                                                                  |
| SMS Failed                     | \[Onesignal] SMS Failed delivery                              | SMS failed to send                                                                     |
| SMS Delivered                  | \[Onesignal] SMS confirmed receipt                            | SMS successfully delivered                                                             |
| SMS Undelivered                | \[Onesignal] SMS Failed delivery                              | The SMS could not be sent.                                                             |

### 이벤트 속성

OneSignal에서 Amplitude로 전송된 모든 이벤트에는 다음 속성이 포함됩니다:

| 속성 이름                | 설명                                   |
| -------------------- | ------------------------------------ |
| **Distinct ID**      | 메시지와 연결된 external\_id                |
| **Message ID**       | 개별 메시지의 식별자                          |
| **Message Name**     | 메시지 이름                               |
| **Message Title**    | 메시지 제목                               |
| **Message Contents** | 메시지 내용                               |
| **message\_type**    | 전송된 메시지 유형: push, in-app, email, SMS |
| **template\_id**     | 사용된 메시지 템플릿(API 및 Journey 메시지)       |
| **subscription\_id** | OneSignal이 설정한 기기/이메일/SMS 식별자        |
| **device\_type**     | 메시지를 받은 기기 유형                        |
| **language**         | 기기의 두 문자 언어 코드                       |
| **source**           | `onesignal`(모든 이벤트의 소스로 표시됨)         |

<Warning>
  Amplitude와 OneSignal 간에 전달 수가 다를 수 있습니다. 자세한 내용은 [전달 데이터가 일치하지 않는 이유는 무엇인가요?](#why-doesnt-delivery-data-match)를 참조하세요.
</Warning>

***

## FAQ

### 코호트 및 세그먼트 수가 일치하지 않는 이유는 무엇인가요?

1. **누락되거나 일치하지 않는 External ID**
   일치하는 OneSignal External ID 및 Amplitude User ID가 있는 사용자만 포함됩니다. 이 통합은 사용자 또는 구독을 생성하지 않습니다.

2. **구독 취소한 사용자**
   OneSignal 세그먼트는 구독된 [구독](./subscriptions)에 대한 수만 표시합니다. 구독 취소된 구독은 Journeys 또는 인앱 메시지에 사용할 수 있습니다.

예를 들어 Amplitude 코호트에 10명의 사용자가 있지만 OneSignal 세그먼트에 8개의 구독이 표시되는 경우 누락된 2명의 사용자는 다음과 같을 수 있습니다:

* OneSignal에 존재하지 않거나 잘못된 External ID를 가지고 있습니다.
* 구독 취소된 구독을 가지고 있습니다.

확인하려면 OneSignal의 **대상 > 사용자** 탭을 확인하여 사용자가 존재하는지, 활성 구독이 있는지 확인하세요.

### 구독 취소한 사용자가 Amplitude에서 동기화되나요?

예, 하지만 현재 OneSignal 세그먼트 수에서는 제외됩니다. 다른 [구독](./subscriptions)이 있거나 구독 유형이 지원하는 경우 Journeys 또는 인앱 메시지를 통해 여전히 메시지를 보낼 수 있습니다.

### 전달 데이터가 일치하지 않는 이유는 무엇인가요?

한 사용자는 여러 [구독](./subscriptions)(푸시 기기, 이메일 주소, 전화번호)을 가질 수 있습니다. 각 구독은 자체 전달 이벤트를 생성합니다. 예를 들어:

* 사용자 1명 = Android 2개 + iOS 1개 + Web 2개 = 푸시 구독 5개
* 푸시 메시지 1개 = 최대 5개의 전송/수신/클릭 이벤트

정확한 소스를 추적하려면 이벤트 속성의 `subscription_id`를 사용하세요.

누락된 이벤트 문제를 해결하려면:

* External ID를 설정하기 위해 사용자가 식별될 때마다 `OneSignal.login`이 호출되는지 확인하세요.
* `OneSignal.logout`가 External ID를 제거하지 않는지 확인하세요.
* External ID를 변경할 수 있는 API 요청 또는 CSV 업로드를 확인하세요.

### 사용자/구독 이벤트를 어떻게 전송할 수 있나요?

사용자 및 구독 수준 이벤트(예: 권한 부여됨, 사용자 로그인/로그아웃)는 자동으로 전송되지 않습니다.

OneSignal SDK에는 Amplitude로 전송할 이러한 이벤트를 추적하는 데 사용할 수 있는 이벤트 리스너가 있습니다:

* User State Observer: [Mobile SDK](./mobile-sdk-reference#addobserver-user-state), [Web SDK](./web-sdk-reference#addeventlistener-user-state)
* Permission Observer: [Mobile SDK](./mobile-sdk-reference#addpermissionobserver-push), [Web SDK](./web-sdk-reference#permissionchange)

### OneSignal 구독 ID가 device\_id로 Amplitude에 추가되는 이유는 무엇인가요?

Amplitude는 중복 제거를 위해 `device_id`를 기대합니다. OneSignal은 이를 위해 `subscription_id`를 사용하며, 이는 자동으로 `device_id`에 매핑됩니다.

자세한 내용은 [Amplitude 문서](https://amplitude.com/docs/apis/analytics/http-v2#event-deduplication)를 참조하세요.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="분석 개요" icon="chart-line" href="./analytics-overview">
    OneSignal 분석, 배송 지표 및 이벤트 추적 개요.
  </Card>

  <Card title="사용자 지정 이벤트" icon="bolt" href="./custom-events">
    사용자 액션을 추적하여 Journeys를 트리거하거나 분석을 강화합니다.
  </Card>
</Columns>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>