데이터 피드

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.

• 사용자의 현재 보상 잔액
• 최신 주문 상태
• 개인화된 제품 추천

​

Data Feeds 작동 방식

1. Data Feed 만들기 – OneSignal이 API에 연결하는 방법을 구성합니다.
2. 메시지 템플릿에 Data Feed 첨부.
3. Liquid 구문을 사용하여 메시지에 응답 필드 삽입.
4. 전송 시, OneSignal은 각 수신자에 대해 API 호출을 수행하고 응답을 파싱한 다음 데이터를 메시지에 삽입합니다.

​

예시: 보상 포인트 표시

Hi {{ first_name }},

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

Keep shopping to earn more points!

​

Data Feed 만들기 및 사용

​

1. Data Feed 구성 설정

• Name: 피드를 구별하는 데 도움이 되는 “Customer Rewards API”와 같은 설명적인 이름. 고유한 이름을 권장하지만 필수는 아닙니다.
• Alias: Liquid 구문에서 사용할 rewards와 같은 짧은 식별자(예: {{ data_feed.rewards.points }}). 고유해야 하며 소문자 영숫자만 사용하고 공백이나 특수 문자는 사용할 수 없습니다.
• Method: OneSignal이 API에 연결하는 데 사용하는 HTTP 메서드. 일반적으로 GET이지만 POST도 지원됩니다.
• URL: API 엔드포인트. Liquid 구문을 지원하므로 OneSignal이 사용자별 데이터를 가져올 수 있습니다.

https://acme.com/customers/user_id={{ external_id }}/rewards

• Headers: API에 필요한 키-값 쌍(예: 인증 토큰). Liquid 구문을 지원합니다.
• Body: 선택적 JSON 요청 본문. Journey 웹훅과 동일하게 Liquid 구문을 지원합니다.

{
	"customer_id": "{{ subscription.external_id }}"
}

​

2. 메시지 템플릿에 Data Feed 첨부

1. Messages > Templates로 이동
2. Message 섹션에서 Personalization 버튼 선택

3. Data Feeds를 켜고 피드 선택

4. 템플릿 저장

​

3. 메시지에서 데이터 사용

{
	"external_id": "a1-b2c3",
	"points": 193,
	"status_level": "Gold"
}

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

• Data Feed 사용
• rewards Data Feed 사용
  • 참고: rewards 피드는 수신자의 external_id로 API를 호출하는 방법을 알고 있습니다
• 응답에서 points 항목(193)과 status_level 항목(Gold)의 값을 삽입

​

요구 사항 및 제한 사항

• 헤더의 인증 토큰으로 단일 단계 인증 수락
• 빠르게 응답. 250ms 미만 권장(전송 속도에 직접 영향을 미침)
• JSON 반환. 현재 다른 형식은 지원되지 않습니다.
  • 다른 형식이 필요한 경우 사용 사례를 공유해 주세요.
• 전송 볼륨 처리. API에 낮은 속도 제한이 있으면 메시지 전달이 느려집니다.
• 적절한 크기의 페이로드 반환. 최상의 성능을 위해 응답을 50KB 미만으로 유지하세요.

• 템플릿당 하나의 Data Feed. 단일 API 응답으로 필요한 모든 데이터를 가져오세요.
• 메시지당 Data Feed당 하나의 API 호출.
• Journeys만 해당. 아직 다른 전송 방법에는 사용할 수 없습니다.
• 연쇄 호출 없음. 한 Data Feed의 페이로드를 사용하여 다른 Data Feed를 호출할 수 없습니다.

​

API 설정

​

인증

Authorization: Bearer YOUR_TOKEN

X-API-Key: YOUR_KEY

​

JSON 요청 본문

​

JSON 응답

​

개인화 매개변수

https://api.example.com/users/{{external_id}}/data
https://api.example.com/rewards?email={{email | url_encode}}

{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}

​

속도 제한

​

오류 처리

​

시작 체크리스트

• 메시지에 어떤 데이터를 표시하고 싶습니까? API에서 채울 항목이 식별된 간단한 개요에서 역으로 작업하면 생각을 정리하는 데 도움이 됩니다.
• 이 데이터는 단일 API 엔드포인트를 통해 사용할 수 있습니까?
• API 요청을 어떻게 인증합니까?
• 개인화된 데이터를 가져오는 데 어떤 식별자 또는 다른 데이터 항목을 사용합니까?
• 해당 식별자가 이미 OneSignal에 저장되어 있습니까? 그렇지 않은 경우 어떻게 채워집니까?
• API가 생성할 요청 볼륨을 처리할 수 있습니까?
• API에 사용자에 대한 데이터가 없으면 어떻게 됩니까?

​

예제 및 고급 사용 사례

• 루프로 반복: 장바구니 포기
• 사용자 지정 이벤트 속성
• 조건부 표시: 주문 상태
• 개인화 없는 자동화
• 개인화된 쿠폰 코드

사용자 장바구니의 항목 배열과 장바구니 총 금액을 반환하는 Data Feed cart가 있다고 가정해 보겠습니다:

{
  "items": [
    {
      "name": "Blue Running Shoes",
      "price": 84.00,
      "image_url": "https://acme.com/blue-running-shoes.png"
    },
    {
      "name": "Protein Bar",
      "price": 5.99,
      "image_url": "https://acme.com/protein-bar.png"
    }
  ],
  "total": 89.99
}

장바구니의 각 항목과 장바구니 총액을 표시하려면 Liquid에서 for 루프를 사용할 수 있습니다:

<ul>
  {% for item in data_feed.cart.items %}
    <li>
      <strong>{{ item.name }}</strong><br>
      ${{ item.price }}<br>
      <img src="{{ item.image_url }}" alt="{{ item.name }}">
    </li>
  {% endfor %}
</ul>

<p>Cart total: ${{ data_feed.cart.total }}</p>

다음과 같은 결과가 나타납니다:

- Blue Running Shoes
- $84.00
- <running shoes image>
- Protein Bar
- $5.99
- <protein bar image>
Cart total: $89.99

이메일 블록 편집기를 사용하는 경우 이러한 종류의 복잡한 Liquid 구문을 삽입할 때, 특히 이미지나 링크를 포함해야 하는 경우 최상의 결과를 얻으려면 사용자 지정 HTML 블록 요소를 사용하세요.

사용자 지정 이벤트를 사용하여 이 장바구니 포기 이메일을 트리거하는 방법이 궁금하신가요? 사용자 지정 이벤트 속성 탭에서 전체 워크플로를 확인하세요.

이전 장바구니 포기 예제를 계속하여, 처음에 해당 특정 장바구니를 가져오는 방법을 어떻게 알 수 있을까요?한 가지 방법은 cart_id가 포함된 속성을 가진 cart_abandoned 사용자 지정 이벤트로 트리거되는 Journey를 만드는 것입니다. 이 예제에서는 해당 이벤트가 API를 통해 OneSignal로 전송됩니다:

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "name": "cart_abandoned",
      "external_id": "user_12345",
      "properties": {
        "cart_id": 98765
      }
    }
  ]
}'

이 이벤트가 발생하면 사용자 user_12345가 Journey에 진입한 다음 이메일을 보내는 노드에 도달합니다. 해당 이메일 템플릿은 cart Data Feed로 설정되어 있으며 URL은 다음과 같이 특정 장바구니의 내용을 검색하도록 설정됩니다:

https://acme.com/carts/{{ journey.event.cart_abandoned.data.cart_id }}

따라서 이 특정 이벤트가 수집되고 Journey를 트리거하면:

1. 98765의 cart_id 값이 Journey에 저장됩니다
2. 이메일 단계에 도달하면 cart Data Feed가 해당 cart_id 값을 참조하고 이를 사용하여 장바구니 API를 호출합니다
3. 반환된 JSON 속성이 파싱되어 위의 이전 예제와 같이 이메일에 삽입됩니다

주문 상태에 따라 Data Feed 콘텐츠를 조건부로 표시하는 방법이 궁금하신가요? 조건부 표시: 주문 상태 탭에서 자세히 알아보세요.

고객 주문의 상태를 포함하되 주문이 배송된 경우에만 추적 번호 링크를 포함하려고 한다고 가정해 보겠습니다. if 문을 사용하여 다음과 같이 할 수 있습니다:

Your order is {{data_feed.order.status}}!

{% if data_feed.order.tracking_number != empty %}
Track it here: {{data_feed.order.tracking_url}}
{% endif %}

여기서 추적 링크는 tracking_number가 존재하는 경우에만 표시됩니다.

Data Feeds는 수신자별로 개인화할 필요 없이 메시지에 최신 정보를 자동으로 삽입하는 데 사용할 수 있습니다.예를 들어, 이메일 상단에 배너 이미지를 삽입하고 휴일 및 기타 월별 이벤트에 맞춰 매월 변경할 수 있습니다. 매월 OneSignal에 새 이미지를 업로드하고 모든 템플릿을 변경하는 것을 기억하는 대신 CMS 또는 기타 자산 관리 위치에서 현재 배너 이미지 URL을 가져오는 Data Feed를 설정할 수 있습니다.다음과 같이 URL에 변수 없이 엔드포인트를 가리키는 banner Data Feed를 설정합니다:

https://acme.com/assets/email-banner

현재 배너 URL과 함께 응답을 반환합니다:

{
	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
}

이메일 템플릿을 {{ data_feed.banner.banner_url }}를 이미지 소스 URL로 사용하도록 설정하여 앞으로 이 프로세스를 자동화합니다.

이 예제에서는 각 수신자에 대해 API에서 고유한 값을 가져오는 Data Feed를 사용하여 이메일로 개인화된 일회용 쿠폰 코드를 전송하는 방법을 다룹니다.

​

목표

다음과 같은 이메일을 전송합니다:

안녕하세요 George님, 앞으로 2시간 내에 예약을 완료하시면 개인 코드 XYZ123ABC로 10% 할인을 받으세요

각 사용자는 이메일 전송 시 외부 API 호출을 통해 실시간으로 생성된 고유 쿠폰 코드를 받으며, 주어진 시간 내에 유효하고 해당 사용자에게만 적용됩니다.

​

사전 요구 사항

• OneSignal에서 이메일 채널 구성(앱에 이메일 기능이 활성화되어 있어야 함)
• 사용자 식별자(예: external_id)와 캠페인 식별자를 수락하고 쿠폰 코드, 할인율, 만료 시간이 포함된 JSON을 반환하는 외부 API
• API가 쿠폰을 생성하는 데 사용할 수 있는 각 사용자의 고유 식별자(예: external_id)
• 이메일을 OneSignal Journey를 통해 전송하는 데 사용되는 세그먼트 또는 트리거(예: “최근 24시간 내 검색 포기”)

​

1단계: Data Feed 만들기

1

Data Feeds로 이동

OneSignal 앱에서 탐색 메뉴의 Data feeds를 선택한 다음 New data feed를 클릭합니다.

2

Data Feed 구성

다음 필드를 구성합니다:

• Data Feed Name: coupon_code_generator
• Alias: coupon
• Method: GET
• URL: https://api.example.com/generate-coupon?userId={{ external_id }}&campaign=AbandonedBooking10
• Headers:
  {
    "Authorization": "Bearer YOUR_API_TOKEN"
  }
  

3

API 응답 참조

API가 다음과 같은 JSON을 반환할 때:

{
  "code": "AB10-5F3K-HT9L",
  "discount_percent": "10%",
  "expires_in_hours": 2
}

이메일 템플릿에서 다음과 같이 값을 참조할 수 있습니다:

• {{ data_feed.coupon.code }}
• {{ data_feed.coupon.discount_percent }}
• {{ data_feed.coupon.expires_in_hours }}

4

Data Feed 테스트 및 활성화

Send Test를 클릭하여 구성을 확인한 다음 Activate를 클릭하여 템플릿에서 사용할 수 있도록 Data Feed를 활성화합니다.

​

2단계: 이메일 템플릿 만들기

1. OneSignal에서 Messages → Email → New Template로 이동합니다
2. 메시지 본문에서 Data Feed 별칭과 필드를 사용합니다. 예를 들어:

<h2>Hi {{ first_name }},</h2>
<p>
Complete your booking in the next {{ data_feed.coupon.expires_in_hours }} hours and save
{{ data_feed.coupon.discount_percent }} with your personal code:
<strong>{{ data_feed.coupon.code }}</strong>
</p>

<p><a href="https://example.com/checkout?coupon={{ data_feed.coupon.code }}">Use Code Now →</a></p>

• {{ data_feed.<alias>.<field> }} 형식으로 Liquid 구문을 사용하세요
• Data Feed가 템플릿에 첨부되어 있는지 확인하세요
• 사용자 지정 Liquid 로직과 함께 드래그 앤 드롭 편집기를 사용하는 경우 HTML 블록을 사용하세요

​

3단계: Data Feed 첨부 및 이메일 트리거

1. 템플릿 작성기의 Personalization에서 Data Feeds를 켜고 피드(coupon_code_generator)를 선택합니다
2. 이렇게 하면 OneSignal이 각 수신자에 대해 전송 시 API 호출을 수행하고, 데이터를 채워 이메일에 삽입합니다
3. 메시지를 자동화하기 위해 Journey를 설정합니다:
   • 진입 조건: “최근 24시간 내 검색 포기”와 같은 세그먼트
   • 대기 조건: booking_completed 사용자 지정 이벤트를 만듭니다. 이 이벤트가 발생하면 Journey를 종료하거나 1시간 후에 계속하도록 대기를 구성합니다. 예약을 완료하면 이메일을 받지 않고 종료되고, 그렇지 않으면 쿠폰을 계속 받습니다.
   • 이메일 전송: 개인화된 쿠폰 이메일 템플릿 사용
   • Journey가 이메일 채널을 사용하고 수신자가 이메일을 구독하고 있는지 확인하세요

​

4단계: 쿠폰 사용 및 추적 관리

백엔드에서 다음을 수행해야 합니다:

1. userId, code, campaign, expiration_time, redeemed 플래그와 함께 생성된 각 코드를 기록합니다
2. 결제 시 코드를 유효성 검사하고 사용된 것으로 표시합니다
3. ROI 분석을 위해 사용 데이터(사용자, 캠페인, 시간)를 기록합니다

​

전체 워크플로 예제

단계	이벤트	작업
1	사용자가 “검색 포기” 세그먼트 트리거	사용자가 세그먼트를 통해 Journey에 진입
2	Journey가 이메일 전송 트리거	OneSignal이 Data Feed를 첨부하고 사용자의 external_id와 캠페인 이름으로 API를 호출합니다
3	API가 JSON 반환	OneSignal이 데이터 피드 쿠폰 필드를 채우고 이메일을 전송합니다
4	사용자가 이메일 수신	예: “안녕하세요 George님! 개인 코드 AB10-5F3K-HT9L로 10% 절약하세요”
5	사용자가 코드 사용	백엔드가 사용을 유효성 검사하고 기록합니다

​

테스트

• 알려진 external_id를 가진 사용자로 테스트합니다
• API를 수동으로 호출하여 올바른 JSON 응답을 확인합니다
• OneSignal 템플릿 편집기의 Preview를 사용하여 데이터 피드 쿠폰 필드가 채워지는지 확인합니다
• 지연 시간과 오류에 대한 API 로그를 확인합니다
• Data Feed 호출이 실패하면 OneSignal은 해당 수신자에게 메시지 전송을 건너뜁니다

​

FAQ

​

Data Feed 값이 메시지에 표시되지 않습니다. 무엇을 확인해야 하나요?

1. Data Feed가 템플릿에 첨부되어 있는지 확인합니다(Personalization > Data Feeds 아래).
2. Liquid 구문이 JSON 응답 구조와 정확히 일치하는지 확인합니다 — {{ data_feed.<alias>.<field> }}.
3. 동일한 식별자로 수동으로 호출했을 때 API 엔드포인트가 유효한 JSON을 반환하는지 확인합니다.
4. 수신자가 OneSignal에 필요한 식별자(예: external_id)를 가지고 있는지 확인합니다.

​

메시지가 천천히 전송되는 이유는 무엇입니까?

​

일부 수신자가 메시지를 받지 못하는 이유는 무엇입니까?

​

템플릿에서 하나 이상의 Data Feed를 사용할 수 있나요?

​

Data Feeds를 푸시 알림이나 SMS에 사용할 수 있나요?

​

메시지 전송 시 API가 다운되면 어떻게 됩니까?

​

관련 페이지