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

# HubSpot

> 네이티브 OneSignal 통합을 사용하여 HubSpot 워크플로에서 푸시 알림, 이메일, SMS 및 인앱 메시지를 자동화합니다.

## 개요

OneSignal HubSpot 통합은 네이티브 워크플로 액션을 통해 HubSpot CRM을 OneSignal에 연결합니다 — 타사 미들웨어가 필요하지 않습니다. 다음을 수행할 수 있습니다:

* **메시지 보내기** — HubSpot 워크플로에서 푸시 알림, 이메일, SMS 트리거
* **사용자 생성** — 이메일 및 SMS 구독과 함께 HubSpot 연락처를 OneSignal에 동기화
* **태그 관리** — HubSpot 연락처 속성에 따라 OneSignal [태그](./add-user-data-tags) 설정 또는 삭제
* **인앱 메시지 타겟팅** — HubSpot이 설정한 태그를 사용하여 인앱 메시지 전달을 제어하는 세그먼트 구축

A/B 테스트, 인텔리전트 전달, 스로틀링, 리타겟팅과 같은 기능은 HubSpot과 함께 OneSignal 대시보드 또는 API를 직접 사용하세요.

<Tip>
  실제 사례는 [HubSpot과 OneSignal 통합을 사용하여 채널 전반의 참여를 높이는 4가지 방법](https://onesignal.com/blog/four-ways-to-use-the-onesignal-integration-with-hubspot-to-boost-engagement-across-channels/)을 읽어보세요.
</Tip>

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/SiGsvdAD6w8?si=8_WPdcNV2COIpaGM" title="OneSignal HubSpot integration overview" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

***

## 사전 요구 사항

* HubSpot 슈퍼 관리자 역할 또는 [앱 마켓플레이스 권한](https://knowledge.hubspot.com/settings/hubspot-user-permissions-guide#admin)
* [유료 OneSignal 플랜](https://onesignal.com/pricing) (무료 플랜에서는 사용 불가)

<Info>
  HubSpot은 2024년 12월에 원래의 타사 OneSignal 앱을 더 이상 지원하지 않습니다. OneSignal은 현재 확장된 기능을 갖춘 자체 HubSpot 앱을 제공합니다. 이전 통합을 사용했다면 아래의 마이그레이션 단계를 참조하세요.
</Info>

<Accordion title="레거시 HubSpot 통합에서 마이그레이션">
  **새 통합 설치**

  아래의 [HubSpot을 OneSignal에 연결](#connect-hubspot-to-onesignal) 섹션에 설명된 대로 OneSignal 대시보드의 **데이터 > 통합**에서 HubSpot 통합을 활성화합니다.

  **워크플로 마이그레이션**

  기존 워크플로의 액션을 교체하기 전에 새 통합을 테스트하기 위한 새 워크플로를 만드는 것을 권장합니다.

  1. **워크플로 복제** — HubSpot **워크플로** 페이지에서 기존 워크플로 옆의 **복제**를 클릭합니다.
  2. **트리거 제거** — 복제된 워크플로에서 게시 시 자동으로 실행되지 않도록 모든 등록 트리거를 제거합니다.
  3. **레거시 액션 교체** — 각 레거시 OneSignal 액션을 제거하고 새 버전으로 교체합니다. 두 앱이 모두 설치된 경우 레거시 앱에는 "Built by HubSpot"이 표시됩니다 — 표시되지 않는 것을 사용하세요.

  <Frame caption="두 앱이 모두 설치된 경우 'Built by HubSpot'이라고 표시되지 않는 OneSignal 액션을 사용하세요.">
    <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a4e1a11d8c343bee5850147e5809d4c94c9966248433ab0ba59e5dce79a5a8b2-image.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=9563ae1d3706dfdbe7f89b4f432a4ae7" width="920" height="1166" data-path="images/docs/a4e1a11d8c343bee5850147e5809d4c94c9966248433ab0ba59e5dce79a5a8b2-image.png" />
  </Frame>

  4. **단일 연락처로 테스트** — 워크플로를 저장하고 게시한 다음 테스트 연락처 하나를 수동으로 등록합니다. 등록 기록을 확인하여 액션이 성공적으로 완료되었는지 확인합니다.

  <Frame caption="마이그레이션된 HubSpot 워크플로 예시.">
    <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/687f1408480774304c930f72d62a82381c1ea11a9c66a8ce6595f568a3dd3b17-image.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=e963ea94239c19696851e6edc4f18c92" width="1482" height="487" data-path="images/docs/687f1408480774304c930f72d62a82381c1ea11a9c66a8ce6595f568a3dd3b17-image.png" />
  </Frame>

  5. **교체 또는 업데이트** — 워크플로가 올바르게 작동하는 것을 확인한 후 원래 워크플로를 복제본으로 교체하거나 원래 워크플로에 동일한 변경 사항을 적용합니다.

  마이그레이션 중 오류가 발생하면 `support@onesignal.com`으로 문의하세요.
</Accordion>

***

## HubSpot을 OneSignal에 연결

### 통합 활성화

OneSignal에서 **데이터 > 통합 > 카탈로그**로 이동하여 **HubSpot**을 선택합니다.

<Frame caption="OneSignal 통합 페이지의 HubSpot 통합 카드.">
  <img src="https://mintcdn.com/onesignal/yCAJt5-6hubcDKe8/images/integrations/catalog-hubspot.png?fit=max&auto=format&n=yCAJt5-6hubcDKe8&q=85&s=91266c81fdf4cea8962c73761cc0c374" width="2902" height="1806" data-path="images/integrations/catalog-hubspot.png" />
</Frame>

**설정 > 인증**을 클릭한 다음 HubSpot 계정을 선택하고 로그인합니다.

<Warning>
  각 OneSignal 앱에 하나의 HubSpot 계정만 연결할 수 있습니다. 테스트 환경이 있는 경우 테스트용으로 다른 OneSignal 앱을 설정할 수 있습니다.
</Warning>

<Frame caption="이 OneSignal 앱에 연결할 HubSpot 계정을 선택합니다.">
  <img src="https://mintcdn.com/onesignal/yCAJt5-6hubcDKe8/images/integrations/hubspot-settings.png?fit=max&auto=format&n=yCAJt5-6hubcDKe8&q=85&s=7faf6812bc71b1fd629c963de34e9efb" width="2902" height="1806" data-path="images/integrations/hubspot-settings.png" />
</Frame>

약관에 동의하고 **앱 연결**을 선택하면 OneSignal로 리디렉션됩니다. 새로 연결된 HubSpot 계정을 열어 연결을 확인합니다.

### 외부 ID로 사용자 매칭

HubSpot 연락처를 OneSignal 사용자에 연결하려면 OneSignal의 [외부 ID](./users)를 HubSpot의 고유 속성(예: 사용자 ID 또는 이메일 주소)과 일치하는 값으로 설정합니다.

앱 또는 웹사이트에서 SDK `login` 메서드를 사용하여 외부 ID를 설정합니다. 매칭이 안정적으로 이루어지도록 앱과 HubSpot 모두에서 쉽게 사용할 수 있는 속성을 선택하세요.

<Info>
  ID 및 구독 관리에 대한 자세한 내용은 [사용자](./users) 및 [구독](./subscriptions)을 참조하세요.
</Info>

### HubSpot 워크플로 생성

HubSpot에서 **자동화 > 워크플로**로 이동하여 **워크플로 생성**을 클릭합니다. **연락처 기반**을 선택하고 등록 트리거를 구성합니다.

OneSignal 액션을 추가하려면 워크플로 편집기에서 \*\*+\*\*를 클릭하고 "OneSignal"을 검색합니다.

<Frame caption="HubSpot의 OneSignal 워크플로 액션.">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7857e4e4ce869bb57dfbce033baf2239054ba81e207a81565a62fe5618fb373b-Screenshot_2025-01-23_at_1.16.10_PM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=ea5f0eb7187127a9f4fef2e338ac5a2c" width="1866" height="1340" data-path="images/docs/7857e4e4ce869bb57dfbce033baf2239054ba81e207a81565a62fe5618fb373b-Screenshot_2025-01-23_at_1.16.10_PM.png" />
</Frame>

모든 OneSignal 액션에는 두 개의 필드가 필요합니다:

<Frame caption="워크플로 액션에서 OneSignal 앱 및 외부 ID 설정.">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a9f3c793693436c0f9ef5c421f600b21ae241310e672303cb2f95fb7f0f8d103-Screenshot_2025-01-31_at_1.40.32_PM.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=162b4cc4654129a4c029d4f0fa5041b8" width="828" height="550" data-path="images/docs/a9f3c793693436c0f9ef5c421f600b21ae241310e672303cb2f95fb7f0f8d103-Screenshot_2025-01-31_at_1.40.32_PM.png" />
</Frame>

* **OneSignal 앱** — 설정 중에 연결한 앱
* **외부 ID** — OneSignal의 외부 ID와 일치하는 HubSpot 연락처 속성

***

## OneSignal 액션

### HubSpot에서 OneSignal 사용자 생성

**사용자 생성** 액션은 연락처가 워크플로를 통과할 때 OneSignal에 [사용자](./users)를 생성합니다. 새 연락처가 추가될 때 OneSignal과 HubSpot을 동기화하는 데 사용합니다.

다음 HubSpot 속성이 설정된 경우 OneSignal은 해당 [구독](./subscriptions)을 자동으로 생성합니다:

* **이메일** → OneSignal에 이메일 구독 생성
* **전화번호** → OneSignal에 SMS 구독 생성

사용자 생성 노드 내에서 외부 ID와 태그를 설정할 수도 있습니다.

<Frame caption="HubSpot 워크플로의 OneSignal 사용자 생성 노드.">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/544e379b13eab1fdddfdaf646a879152ea6251f1833870f5ed2671e0e2558506-Screenshot_2025-03-10_at_4.34.19_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=c12475968bf18c8353ef576882855d03" width="1030" height="817" data-path="images/docs/544e379b13eab1fdddfdaf646a879152ea6251f1833870f5ed2671e0e2558506-Screenshot_2025-03-10_at_4.34.19_PM.png" />
</Frame>

<Warning>
  OneSignal 앱에 [더블 옵트인](./sms-opt-in-and-collection#promotional-double-opt-in-form)이 활성화된 경우 새 SMS 구독은 자동으로 옵트인 메시지를 받습니다. 사용자 생성 노드에서 이를 비활성화할 수 있습니다 — SMS 구독은 생성되지만 사용자가 별도로 옵트인할 때까지 구독되지 않습니다.
</Warning>

***

### HubSpot에서 OneSignal 태그 편집

**태그 편집** 액션은 매칭된 OneSignal 사용자의 [태그](./add-user-data-tags)를 설정하거나 삭제합니다. 태그는 [메시지 개인화](./message-personalization)와 [세분화](./segmentation)를 가능하게 하며, [HubSpot에서 인앱 메시지를 타겟팅](#send-in-app-messages-with-hubspot)하는 메커니즘입니다.

#### 태그 설정

태그 필드에 JSON 객체를 입력합니다:

```json theme={null}
{ "welcome": "1", "name": "<First Name property>" }
```

워크플로 편집기에서 HubSpot의 속성 토큰 삽입기를 사용하여 HubSpot 연락처 속성을 태그 값으로 삽입할 수 있습니다. 예를 들어, OneSignal에서 메시지를 개인화하기 위해 사용자의 이름을 태그로 추가하는 경우.

#### 태그 삭제

태그를 제거하려면 값을 빈 문자열로 설정합니다:

```json theme={null}
{ "old_tag": "" }
```

태그가 사용자에게 존재하지 않으면 무시됩니다.

<Frame caption="태그 편집 액션에서 두 개의 태그('welcome'과 'name')를 설정하고 하나('key')를 삭제.">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/bb4ff8e3b5c8bf3742d721f94791f2e97137b89f58f3e862ff650b2c58d1e43a-Screenshot_2025-01-23_at_1.46.35_PM.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=6df8727cc9c5dd212c0c4ac62aeae71a" width="1866" height="1340" data-path="images/docs/bb4ff8e3b5c8bf3742d721f94791f2e97137b89f58f3e862ff650b2c58d1e43a-Screenshot_2025-01-23_at_1.46.35_PM.png" />
</Frame>

***

### HubSpot 워크플로에서 메시지 보내기

**알림 보내기** 액션은 매칭된 OneSignal 사용자에게 푸시 알림, 이메일 또는 SMS를 전달합니다.

<Tip>
  이메일이 아닌 **OneSignal 외부 ID**로 사용자를 매칭하세요. 이메일 매칭은 `addEmail` SDK 메서드를 사용하여 이메일을 설정한 고객을 위한 레거시 옵션입니다.
</Tip>

<Frame caption="OneSignal 알림 보내기 액션 구성.">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c240529d9ab770443b90a8eb61db498edde6fdacc2c4a8efc8e1eb6c26582955-Screenshot_2025-01-23_at_2.19.19_PM.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=bf5975fd590611d5aedc7f297d4262d2" width="1866" height="1340" data-path="images/docs/c240529d9ab770443b90a8eb61db498edde6fdacc2c4a8efc8e1eb6c26582955-Screenshot_2025-01-23_at_2.19.19_PM.png" />
</Frame>

**템플릿 사용**

OneSignal 대시보드 또는 API에서 생성된 사전 정의된 [템플릿](./templates)을 선택합니다. 템플릿은 푸시 알림, 이메일, SMS를 지원합니다.

**양식 필드 사용**

템플릿을 선택하지 않으면 제목, 부제목, 메시지, 이미지 URL, 실행 URL 필드를 사용하여 워크플로 액션에서 직접 푸시 알림을 작성할 수 있습니다. 이메일과 SMS는 템플릿을 통해서만 사용 가능합니다.

양식 필드 옵션을 사용하면 HubSpot 연락처 속성(예: `이름`)을 삽입하여 알림 콘텐츠를 개인화할 수 있습니다.

***

#### HubSpot으로 인앱 메시지 보내기

인앱 메시지는 HubSpot 워크플로에서 직접 보낼 수 없습니다. 대신 HubSpot을 사용하여 사용자에게 태그를 지정하고 OneSignal에서 세그먼트 기반 인앱 메시지로 해당 사용자를 타겟팅합니다.

<Steps>
  <Step title="HubSpot에서 사용자에게 태그 지정">
    HubSpot 워크플로에서 [태그 편집](#edit-onesignal-tags-from-hubspot) 액션을 사용하여 연락처에 태그를 설정합니다. 예: `{ "hubspot_campaign": "spring_promo" }`.
  </Step>

  <Step title="OneSignal에서 세그먼트 생성">
    OneSignal 대시보드에서 **오디언스 > 세그먼트**로 이동하여 **새 세그먼트**를 클릭합니다. HubSpot이 설정한 태그 키와 값과 일치하는 **사용자 태그** 필터를 추가합니다(예: `hubspot_campaign`이 `spring_promo`).
  </Step>

  <Step title="인앱 메시지 생성">
    **메시지 > 인앱**으로 이동하여 새 인앱 메시지를 생성합니다. **오디언스**에서 **특정 세그먼트에 표시**를 선택하고 생성한 세그먼트를 선택합니다.

    사용자가 HubSpot 워크플로를 통과하여 태그를 받으면 즉시 세그먼트에 추가됩니다.
  </Step>

  <Step title="트리거 구성">
    태그만으로는 인앱 메시지가 트리거되지 않습니다. 사용자가 앱을 적극적으로 사용 중일 때 태그가 설정된 경우 다음 세션까지 인앱 메시지가 표시되지 않습니다(앱이 30초 이상 백그라운드에 있으면 새 세션이 시작됩니다).

    사용 가능한 트리거:

    * **앱 열기 시** — 사용자가 다음에 앱을 열 때 표시
    * **세션 시간** — 세션 내 설정된 초 수 후 표시
    * **마지막 인앱 메시지 이후 시간** — 연속 메시지 방지
    * **프로그래밍 방식** — OneSignal SDK를 사용하여 앱 코드에서 트리거

    AND/OR 연산자로 트리거를 결합하는 방법은 [인앱 메시지 트리거](./iam-triggers)를 참조하세요.
  </Step>
</Steps>

***

## 일반적인 워크플로 패턴

HubSpot 워크플로는 **등록 트리거**(워크플로를 시작하는 이벤트)와 **OneSignal 액션**(OneSignal에서 사용자에게 일어나는 일)을 결합합니다. 아래는 일반적인 사용 사례에 대한 권장 패턴입니다.

<Info>
  아래의 모든 워크플로 패턴은 이미 [HubSpot을 OneSignal에 연결](#connect-hubspot-to-onesignal)했고 [외부 ID를 통해 사용자를 매칭](#match-users-with-external-id)하고 있다고 가정합니다.
</Info>

### 환영 및 온보딩

새 사용자가 가입할 때 환영 메시지를 보내고 온보딩 인앱 메시지를 위해 태그를 지정합니다.

| 단계         | 유형                | 구성                                                                               |
| ---------- | ----------------- | -------------------------------------------------------------------------------- |
| **등록 트리거** | HubSpot           | 연락처 속성 `고객이 된 날짜`가 알려진 경우                                                        |
| **액션 1**   | OneSignal: 사용자 생성 | 외부 ID를 앱과 일치하는 HubSpot 연락처 속성(예: 사용자 ID 또는 이메일 주소)으로 설정                          |
| **액션 2**   | OneSignal: 태그 편집  | `{ "onboarding": "active", "name": "<First Name>" }` — 이름 값에 HubSpot 이름 속성 토큰 삽입 |
| **액션 3**   | OneSignal: 알림 보내기 | 환영 푸시 템플릿 사용 또는 개인화된 인사말로 인라인 작성                                                 |

<Tip>
  새 사용자를 첫 실행 시 앱에서 안내하는 `onboarding` = `active` 세그먼트를 타겟팅하는 [인앱 메시지](#send-in-app-messages-with-hubspot)와 결합하세요.
</Tip>

### 재참여

최근 앱을 방문하지 않은 사용자에게 연락합니다.

| 단계             | 유형                | 구성                                        |
| -------------- | ----------------- | ----------------------------------------- |
| **등록 트리거**     | HubSpot           | 연락처 속성 `마지막 활동 날짜`가 14일 이상 전              |
| **액션 1**       | OneSignal: 알림 보내기 | 재참여 푸시 템플릿 사용(예: "보고싶었습니다 — 새로운 소식이 있어요") |
| **지연**         | HubSpot: 3일 대기    | —                                         |
| **If/then 분기** | HubSpot           | 연락처가 등록 후 사이트를 방문했는지 확인                   |
| **예 분기**       | OneSignal: 태그 편집  | `{ "reengaged": "true" }`                 |
| **아니오 분기**     | OneSignal: 알림 보내기 | 더 강한 인센티브를 포함한 이메일 템플릿 사용                 |

### 라이프사이클 단계 변경

HubSpot의 라이프사이클 단계 변경을 OneSignal 태그와 동기화하여 다양한 사용자 세그먼트를 타겟팅할 수 있습니다.

| 단계             | 유형                | 구성                                                                           |
| -------------- | ----------------- | ---------------------------------------------------------------------------- |
| **등록 트리거**     | HubSpot           | 연락처 속성 `라이프사이클 단계`가 임의의 값으로 변경                                               |
| **액션 1**       | OneSignal: 태그 편집  | `{ "lifecycle_stage": "<Lifecycle Stage>" }` — 값에 HubSpot 라이프사이클 단계 속성 토큰 삽입 |
| **If/then 분기** | HubSpot           | 라이프사이클 단계 = `고객`인지 확인                                                        |
| **예 분기**       | OneSignal: 알림 보내기 | "환영합니다" 푸시 또는 이메일 템플릿 사용                                                     |

### 거래 성사 / 구매 후

거래 성사 후 감사 메시지를 트리거하고 업셀 캠페인을 위해 사용자에게 태그를 지정합니다.

| 단계         | 유형                | 구성                                                                             |
| ---------- | ----------------- | ------------------------------------------------------------------------------ |
| **등록 트리거** | HubSpot           | 거래 속성 `거래 단계` = `성사`                                                           |
| **액션 1**   | OneSignal: 태그 편집  | `{ "customer": "true", "deal_value": "<Amount>" }` — 값에 HubSpot 거래 금액 속성 토큰 삽입 |
| **액션 2**   | OneSignal: 알림 보내기 | 감사 이메일 템플릿 사용                                                                  |
| **지연**     | HubSpot: 7일 대기    | —                                                                              |
| **액션 3**   | OneSignal: 알림 보내기 | 업셀/크로스셀 푸시 템플릿 사용                                                              |

<Note>
  거래 기반 워크플로는 HubSpot에서 **거래 기반** 워크플로 유형이 필요합니다. 관련 연락처의 외부 ID를 사용하여 OneSignal 사용자를 매칭합니다.
</Note>

### 인앱 메시지를 통한 프로모션 캠페인

HubSpot 목록 또는 양식에 의해 트리거된 인앱 메시지로 특정 오디언스를 타겟팅합니다.

| 단계         | 유형               | 구성                                     |
| ---------- | ---------------- | -------------------------------------- |
| **등록 트리거** | HubSpot          | 연락처가 정적 또는 활성 목록(예: "봄 세일 대상자")의 멤버가 됨 |
| **액션 1**   | OneSignal: 태그 편집 | `{ "promo": "spring_2025" }`           |

그런 다음 [HubSpot으로 인앱 메시지 보내기](#send-in-app-messages-with-hubspot) 단계를 따라 `promo` = `spring_2025`와 일치하는 OneSignal 세그먼트를 만들고 해당 세그먼트에 대한 인앱 메시지를 구성합니다.

캠페인이 끝난 후 사용자를 캠페인에서 제거하려면 태그를 삭제하는 두 번째 워크플로를 만듭니다:

| 단계         | 유형               | 구성                 |
| ---------- | ---------------- | ------------------ |
| **등록 트리거** | HubSpot          | 날짜 기반, 캠페인 종료일로 설정 |
| **액션 1**   | OneSignal: 태그 편집 | `{ "promo": "" }`  |

***

## 문제 해결

### HubSpot에서 워크플로 액션이 "실패"로 표시됨

1. **오류 메시지 확인** — HubSpot 워크플로 등록 기록에서 실패한 액션을 펼칩니다. 오류 메시지는 종종 원인을 나타냅니다(예: "사용자를 찾을 수 없음", "잘못된 앱 ID").
2. **외부 ID 확인** — 외부 ID로 사용되는 HubSpot 연락처 속성이 OneSignal의 사용자와 일치하는지 확인합니다. **OneSignal > 오디언스 > 사용자**에서 사용자 프로필을 확인하고 외부 ID로 검색합니다.
3. **통합이 활성화되어 있는지 확인** — **OneSignal > 데이터 > 통합 > HubSpot**으로 이동하여 연결 상태가 활성 상태인지 확인합니다.

### 메시지는 보냈지만 사용자가 받지 못함

1. **구독 확인** — 사용자는 보내는 채널(푸시, 이메일 또는 SMS)에 대한 활성 구독이 있어야 합니다. OneSignal의 사용자 프로필에서 **구독**을 확인합니다.
2. **세그먼트 멤버십 확인** — 세그먼트 타겟팅이 있는 템플릿을 사용하는 경우 사용자가 타겟 세그먼트에 속하는지 확인합니다.
3. **메시지 보고서 검토** — OneSignal 대시보드에서 **메시지**로 이동하여 메시지를 찾고 전달 보고서를 확인하여 메시지가 전달, 삭제 또는 오류가 발생했는지 확인합니다.

### OneSignal 사용자에 태그가 나타나지 않음

1. **외부 ID 매칭 확인** — 워크플로의 외부 ID가 기존 OneSignal 사용자와 일치하지 않으면 태그 편집 액션이 자동으로 실패합니다. 사용자가 존재하는지 확인하기 위해 태그 편집 전에 **사용자 생성** 액션을 사용하세요.
2. **JSON 형식 확인** — 태그는 유효한 JSON 객체여야 합니다. 일반적인 실수로는 키나 값 주위에 따옴표가 없거나, 후행 쉼표가 있거나, 큰따옴표 대신 작은따옴표를 사용하는 것이 있습니다.
3. **빈 값 확인** — 태그 값을 `""`로 설정하면 태그가 삭제됩니다. 삽입되는 HubSpot 연락처 속성이 비어 있지 않은지 확인합니다.

### 인앱 메시지가 표시되지 않음

아래 FAQ의 [태그가 설정된 후 인앱 메시지가 표시되지 않은 이유는?](#why-didnt-my-in-app-message-display-after-the-tag-was-set)를 참조하세요.

***

## FAQ

### HubSpot과 OneSignal 간에 어떤 데이터가 공유됩니까?

| HubSpot | 방향 | OneSignal | 설명                                                                                           |
| ------- | -- | --------- | -------------------------------------------------------------------------------------------- |
| 연락처 속성  | →  | 외부 ID, 태그 | HubSpot 연락처 데이터는 [외부 ID](./users)와 [태그](./add-user-data-tags)를 통해 OneSignal 사용자를 매칭하고 강화합니다. |
| 워크플로    | ←  | 메시지 템플릿   | OneSignal [템플릿](./templates)은 HubSpot 워크플로 액션에서 선택할 수 있습니다.                                  |

통합은 HubSpot 목록, 거래 또는 회사 레코드를 OneSignal에 자동으로 동기화하지 않습니다. 필요한 데이터를 명시적으로 전달하려면 워크플로 액션을 사용하세요.

### 외부 ID가 OneSignal 사용자와 일치하지 않으면 어떻게 됩니까?

**알림 보내기**와 **태그 편집** 액션은 자동으로 실패합니다 — 메시지가 보내지지 않고 태그도 설정되지 않습니다. 워크플로의 다른 OneSignal 액션 앞에 항상 **사용자 생성** 액션을 배치하여 사용자가 OneSignal에 존재하는지 확인하세요.

### HubSpot 목록을 사용하여 OneSignal 세그먼트를 타겟팅할 수 있습니까?

직접은 불가능합니다. HubSpot 목록과 OneSignal 세그먼트는 독립적인 시스템입니다. 연결하려면 HubSpot 목록에서 연락처를 등록하는 워크플로를 만들고 **태그 편집** 액션을 사용하여 태그를 설정합니다. 그런 다음 해당 태그를 기반으로 OneSignal 세그먼트를 구축합니다. 구체적인 예는 [인앱 메시지를 통한 프로모션 캠페인](#promotional-campaign-via-in-app-message)을 참조하세요.

### HubSpot에서 어떤 OneSignal 채널을 보낼 수 있습니까?

푸시 알림은 템플릿 또는 양식 필드를 사용하여 보낼 수 있습니다. 이메일과 SMS는 OneSignal에서 만든 [템플릿](./templates)을 사용해서만 보낼 수 있습니다. 인앱 메시지는 HubSpot 워크플로에서 보낼 수 없습니다 — 대신 [태그 및 세그먼트 패턴](#send-in-app-messages-with-hubspot)을 사용하세요.

### 태그가 설정된 후 인앱 메시지가 표시되지 않은 이유는?

태그만으로는 인앱 메시지가 트리거되지 않습니다. 태그는 사용자를 세그먼트에 추가하지만 인앱 메시지를 표시하려면 여전히 **트리거**가 필요합니다. 사용자가 앱을 적극적으로 사용 중일 때 태그가 설정된 경우 다음 세션(30초 이상 백그라운드)까지 표시되지 않습니다. 가장 안정적인 동작을 위해 인앱 메시지 트리거를 **앱 열기 시**로 설정하세요. 모든 트리거 옵션은 [인앱 메시지 트리거](./iam-triggers)를 참조하세요.

### HubSpot 웹훅을 사용하여 OneSignal API를 직접 호출할 수 있습니까?

예. HubSpot의 **커스텀 코드** 워크플로 액션을 사용하여 외부 API에 HTTP 요청을 만들 수 있습니다. [OneSignal REST API](/reference/create-notification)를 호출하여 네이티브 통합 외부에서 메시지 보내기, 사용자 생성, 태그 업데이트를 할 수 있습니다. 이는 네이티브 액션이 다루지 않는 사용 사례(개별 사용자가 아닌 세그먼트로 보내기 등)에 유용합니다.

### OneSignal 메시지 이벤트를 HubSpot으로 다시 보낼 수 있습니까?

예. [이벤트 스트림](./event-streams)을 사용하여 OneSignal 메시지 이벤트(보낸, 클릭된 등)를 웹훅 엔드포인트로 내보낼 수 있습니다. 이러한 이벤트를 HubSpot의 [커스텀 이벤트 API](https://developers.hubspot.com/docs/api/analytics/events)로 라우팅하거나 미들웨어 서비스를 사용하여 OneSignal 참여 데이터를 기반으로 HubSpot 연락처 속성을 업데이트할 수 있습니다.

### HubSpot에서 OneSignal 저니를 트리거할 수 있습니까?

HubSpot 사용자를 OneSignal [저니](./journeys-overview)에 넣는 방법은 두 가지입니다:

1. **태그** — [태그 편집](#edit-onesignal-tags-from-hubspot) 액션을 사용하여 사용자에게 태그를 설정합니다. 해당 태그를 기반으로 OneSignal에서 세그먼트를 만들고 해당 세그먼트를 저니 진입 조건으로 사용합니다.
2. **커스텀 이벤트** — HubSpot의 **커스텀 코드** 액션을 사용하여 [OneSignal 커스텀 이벤트 API](/reference/create-custom-events)를 호출합니다. 이는 저니 진입 트리거 역할을 할 수 있습니다.

### HubSpot에서 OneSignal로 커스텀 이벤트를 보낼 수 있습니까?

네이티브 워크플로 액션을 통해서는 불가능합니다. 네이티브 통합은 사용자 생성, 태그 편집, 알림 보내기를 지원합니다. 커스텀 이벤트를 보내려면 HubSpot의 **커스텀 코드** 액션을 사용하여 [OneSignal 커스텀 이벤트 API](/reference/create-custom-events)를 직접 호출하세요.

### 어떤 HubSpot 등록 트리거가 OneSignal과 함께 작동합니까?

모든 HubSpot 등록 트리거가 작동합니다 — OneSignal 액션은 연락처가 어떻게 등록되었는지에 관계없이 실행되는 표준 워크플로 액션입니다. 일반적인 트리거로는 다음이 있습니다:

* **연락처 속성 변경** (라이프사이클 단계, 리드 상태, 마지막 활동 날짜)
* **양식 제출** (가입 양식, 데모 요청, 이벤트 등록)
* **목록 멤버십** (정적 또는 활성 목록에 추가됨)
* **거래 단계 변경** (파이프라인 진행, 성사/실패)
* **날짜 기반** (예약된 캠페인, 이벤트 이후 시간)
* **수동 등록** (일회성 발송 또는 테스트용)

### 라이브 전에 워크플로를 테스트하는 방법은?

1. 워크플로를 만들고 모든 자동 등록 트리거 제거
2. 워크플로 저장 및 게시
3. 단일 테스트 연락처 수동 등록
4. HubSpot의 등록 기록에서 액션 성공/실패 확인
5. OneSignal 대시보드에서 사용자, 태그 또는 메시지 확인
6. 확인 후 등록 트리거 추가 및 재게시

***

<Columns cols={3}>
  <Card title="태그" icon="tag" href="./add-user-data-tags">
    개인화 및 세분화를 위해 사용자에게 커스텀 속성을 추가합니다.
  </Card>

  <Card title="템플릿" icon="file-lines" href="./templates">
    푸시, 이메일, SMS용 재사용 가능한 메시지 템플릿을 만듭니다.
  </Card>

  <Card title="저니" icon="route" href="./journeys-overview">
    사용자 행동에 의해 트리거되는 자동화된 멀티채널 메시지 플로를 구축합니다.
  </Card>

  <Card title="이벤트 스트림" icon="bolt" href="./event-streams">
    웹훅을 통해 실시간 메시지 이벤트를 외부 플랫폼으로 내보냅니다.
  </Card>

  <Card title="세분화" icon="users" href="./segmentation">
    태그, 행동, 사용자 속성을 기반으로 오디언스 세그먼트를 구축합니다.
  </Card>

  <Card title="인앱 메시지 트리거" icon="bell" href="./iam-triggers">
    인앱 메시지가 사용자에게 표시되는 시기와 방법을 제어합니다.
  </Card>
</Columns>