메인 콘텐츠로 건너뛰기
Liquid은 이메일, 푸시, SMS, 인앱 및 Live Activities를 포함한 채널 전반에서 메시지를 개인화하기 위해 OneSignal에서 지원하는 템플릿 언어입니다. 태그, 필터 및 조건을 사용하여 메시지 콘텐츠를 동적으로 사용자 지정합니다. Liquid 구문에 대한 자세한 내용은 공식 Liquid 문서를 참조하세요.

​
메시지 유형별 지원 필드

  • 이메일
  • 푸시
  • SMS
  • 인앱 메시지
  • 라이브 활동
  • 제목, 답장 대상 및 사전 헤더
  • 메시지 본문
  • HTML 블록의 이미지 대체. 예시: <img src="{{image_url}}"/>
  • URL, 메일 보내기 및 기타 필드와 같은 버튼 블록 작업.

​
기본 구문

Liquid은 두 가지 주요 구문 구조를 사용합니다:
  1. 출력 태그: {{ ... }} - 변수 또는 객체의 데이터를 표시합니다.
  2. 로직 태그: {% ... %} - 조건문 또는 루프를 실행합니다.

​
데이터 소스

소스예시설명
태그{{ first_name }}OneSignal SDK 또는 API (tags)
속성{{ subscription.email }}시스템 관리 (email, external_id, language 등)
저니 이름{{ journey.name }}시스템 관리
사용자 지정 데이터{{ message.custom_data.key }}메시지 생성 API에서 전달된 custom_data
데이터 피드{{ data_feed.cart.size }}데이터 피드를 사용하면 전송 시 API에서 실시간 데이터를 메시지로 직접 가져올 수 있습니다.
사용자 지정 이벤트{{ journey.last_event.name }}이벤트 트리거 저니, 다음까지 대기 노드를 통해 설정

​
조건문

​
연산자

  • ==, !=, >, <, >=, <=
  • and, or
  • contains (문자열 또는 배열)
연산은 오른쪽에서 왼쪽으로 실행됩니다. 괄호는 지원되지 않습니다.
liquid
{% if true or false and false %}
  This is true.
{% endif %}

​
if, elsif, else

liquid
{%- assign userLang = subscription.language -%}
{% if userLang == "es" -%}
Hola {{ first_name }}!
{%- elsif userLang == "fr" -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}

​
unless

liquid
{% unless level == "1" %}
  Great job getting past the first level!
{% endunless %}

​
필터

{{ variable | filter }}를 사용하여 필터를 적용하여 데이터 표시 방식을 조정합니다.

​
default

속성이 비어 있거나 존재하지 않는 경우 기본값을 할당합니다.
liquid
Hello {{ first_name | default: "there" }}.

​
date

date 필터는 타임스탬프를 다른 날짜 형식으로 변환합니다. 이 구문의 형식은 strftime과 동일합니다. 입력은 Ruby의 Time.parse와 동일한 형식을 사용합니다. 태그로 날짜를 초 단위 unix 타임스탬프로 설정합니다. 이렇게 하면 liquid 구문 개인화 및 시간 연산자를 사용한 세분화를 모두 사용할 수 있습니다. 예를 들어 태그는 다음과 같을 수 있습니다: bill_due : 1687968776
liquid
{{ bill_due | date: "%a, %b %d, %y" }}
{{ "now" | date: "%Y-%m-%d %H:%M" }}
Result
Wed, Jun 28, 23
liquid
{{ bill_due | date: "%Y" }}
Result
2023
날짜 형식은 올바른 형식의 날짜가 포함된 경우 문자열에서 작동합니다.
liquid
{{ "March 14, 2016" | date: "%b %d, %y" }}
Result
Mar 14, 16
현재 시간을 가져오려면 date 필터와 함께 특수 단어 now (또는 today)를 전달합니다.
liquid
This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
Result
This message was sent at 2022-11-02 14:39.
현재 시간은 메시지가 수신자에게 전송된 시간을 기준으로 메시지에 렌더링됩니다. 메시지를 테스트하는 경우 테스트 메시지가 전송된 시간이 현재 시간으로 표시됩니다.

​
capitalize

이 필터는 문자열의 첫 문자를 대문자로 만들고 나머지 문자를 소문자로 변환합니다.
liquid
{{ "my GREAT title" | capitalize }}
Result
My great title

​
round

이 필터는 숫자를 가장 가까운 정수로 반올림하거나 인수로 숫자가 전달된 경우 해당 소수 자릿수로 반올림합니다.
liquid
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
Result
1
3
183.36

​
pluralize

이 필터는 주어진 숫자를 기준으로 문자열의 단수 또는 복수 형식을 반환합니다. 숫자는 정수여야 하며 문자열로 제공할 수 있습니다. 문자열의 단수 및 복수 형식을 모두 제공해야 합니다.
liquid
{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}
Result
singular
plural
1 person
2 people
2 people

​
반복

​
for 루프

코드 블록을 반복적으로 실행합니다. for 루프 내에서 사용 가능한 속성의 전체 목록은 for 루프 객체를 참조하세요.
liquid
{% for product in message.custom_data.products %}
  - {{ product.name }}
  {% else %}
    Sorry, we're sold out of all products.
  {% endfor %}
Request Body
{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
    "template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c",
    "custom_data": {
      "products": [
        { "name": "Sweater" },
        { "name": "Hat" },
        { "name": "Shirt" }
      ]
    }
  }
Results
  - Sweater
  - Hat
  - Shirt

  // if message.custom_data.products is empty
  Sorry we're sold out of all products
강력하고 유연하지만 liquid 구문에서 for 루프를 사용하면 특정 드문 경우에 알림 전달 성능이 저하될 수 있습니다. for 루프 사용에 주의하세요. 또한 일부 푸시 채널 필드(contents, headings, subtitle, apns_alert 및 url)에서 for 루프 사용을 방지한다는 점에 유의하세요.

​
limit & offset

루프를 지정된 반복 횟수로 제한합니다. 예를 들어 메시지에 4개의 제품만 표시하려는 경우 제한 및 오프셋을 사용하여 표시되는 제품 수를 지정할 수 있습니다.
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
Result
1 2
지정된 인덱스에서 루프를 시작하려면 오프셋 값을 추가합니다:
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: 3 %}
  {{ number }}
{% endfor %}
```text Result
1 2 3
4 5 6

​
where

주어진 속성 값을 가진 객체만 포함하는 배열을 생성하거나 기본적으로 참 값을 가진 객체만 포함합니다. 이 예시에서는 제품 목록이 있고 주방 제품을 별도로 표시하려고 한다고 가정합니다. where를 사용하면 type이 kitchen인 제품만 포함하는 배열을 만들 수 있습니다.
Data
products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]
liquid
All products:
{% for product in products %}
- {{ product.name }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}
Result
All products:
  - Vacuum
  - Spatula
  - Television
  - Garlic press

Kitchen products:
- Spatula
- Garlic press

​
문자열 조작

때때로 사용자에게 직접 표시하기에 적합하지 않은 형식의 문자열이 포함된 데이터 태그가 있을 수 있으며, 형식을 조정하기 위해 문자열을 조작해야 할 수 있습니다. 아래는 문자열을 조정하는 데 사용할 수 있는 liquid 구문 명령 표입니다. 태그와 메시지에 직접 작성된 문자열 모두에서 문자열 조작을 사용할 수 있습니다.
명령어설명예시예시 출력
replace하위 문자열을 다른 문자열로 바꿉니다.{{ 'hello world' | replace: 'world', 'there' }}hello there
capitalize문자열의 첫 글자를 대문자로 만듭니다.{{ 'hello' | capitalize }}Hello
upcase문자열을 대문자로 변환합니다.{{ 'hello' | upcase }}HELLO
downcase문자열을 소문자로 변환합니다.{{ 'HELLO' | downcase }}hello
strip문자열에서 선행 및 후행 공백을 제거합니다.{{ ' hello ' | strip }}hello
strip_html문자열에서 모든 HTML 태그를 제거합니다.{{ '<p>hello</p>' | strip_html }}hello
truncate문자열을 지정된 길이로 줄이고 필요한 경우 줄임표(…)를 추가합니다.{{ 'This is a long sentence' | truncate: 10 }}This is a…
truncatewords특정 단어 수 이후에 문자열을 자릅니다.{{ 'This is a long sentence' | truncatewords: 2 }}This is…
replace_first하위 문자열의 첫 번째 발생을 바꿉니다.{{ 'hello world' | replace_first: 'world', 'there' }}hello there
prepend다른 문자열의 시작 부분에 문자열을 추가합니다.{{ 'world' | prepend: 'hello ' }}hello world
append다른 문자열의 끝에 문자열을 추가합니다.{{ 'hello' | append: ' world' }}hello world
lstrip문자열에서 선행 공백을 제거합니다.{{ ' hello' | lstrip }}hello
rstrip문자열에서 후행 공백을 제거합니다.{{ 'hello ' | rstrip }}hello

​
자주 묻는 질문

​
대체가 작동하지 않는 이유는 무엇인가요?

  • 인앱 메시지는 속성 대체를 지원하지 않습니다.
  • “테스트 메시지 보내기”를 사용할 때는 태그 대체가 작동하지 않습니다.
  • 태그 키는 영숫자여야 하거나 _ 및 -를 사용해야 합니다(마침표나 공백 없음).
  • 미리보기 모드에서는 대체가 표시되지 않습니다. 테스트하려면 실제 메시지를 보내세요.

​
공백 및 개행을 제어하는 방법은 무엇인가요?

하이픈을 사용하세요: {{- ... -}}, {%- ... -%}는 주변 공백을 제거합니다. 자세한 내용은 공백 제어를 참조하세요.

​
사용자 생성 콘텐츠를 처리하는 방법은 무엇인가요?

사용자 생성 텍스트를 {% raw %} 및 {% endraw %}로 래핑하여 Liquid 구문 분석을 방지하세요. “raw” 구문을 참조하세요.
json
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}