Liquid 구문 사용

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

기본 구문

Liquid은 두 가지 주요 구문 구조를 사용합니다:

출력 태그: {{ ... }} — 변수 또는 객체의 데이터를 표시합니다.
로직 태그: {% ... %} — 조건문 또는 루프를 실행합니다.

조건문

연산자

==, !=, >, <, >=, <=
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

날짜 형식은 올바른 형식의 날짜가 포함된 경우 문자열에서 작동합니다.

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 루프 내에서 사용 가능한 속성의 전체 목록은 Liquid 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": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "custom_data": {
    "products": [
      { "name": "Sweater" },
      { "name": "Hat" },
      { "name": "Shirt" }
    ]
  }
}

Result

- Sweater
- Hat
- Shirt

(message.custom_data.products가 비어 있는 경우)
죄송합니다, 모든 제품이 품절되었습니다.

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

`limit` & `offset`

루프를 지정된 반복 횟수로 제한합니다. 예를 들어 메시지에 4개의 제품만 표시하려는 경우 제한 및 오프셋을 사용하여 표시되는 제품 수를 지정할 수 있습니다.

Data

great_numbers = [1,2,3,4,5,6]

liquid

{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}

Result

1 2

지정된 인덱스에서 루프를 시작하려면 오프셋 값을 추가합니다:

Data

great_numbers = [1,2,3,4,5,6]

liquid

{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: 3 %}
  {{ number }}
{% endfor %}

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

문자열 조작

문자열 필터를 적용하여 메시지에서 태그 값이나 인라인 문자열이 표시되는 방식을 조정합니다.

명령어	설명	예시	예시 출력
`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

자주 묻는 질문

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

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

`default`와 `if/else` 중 어떤 것을 사용해야 하나요?

변수 값만 폴백이 필요하고 주변 텍스트가 동일하게 유지될 때는 default 필터를 사용하세요.

liquid

Hello {{ name | default: "there" }}!

Result (name = "Jon")

Hello Jon!

Result (name이 비어 있는 경우)

Hello there!

주변 텍스트, 구두점 또는 문장 구조도 변수 존재 여부에 따라 변경되어야 할 때는 if/else 조건 논리를 사용하세요.

liquid

{% if name %}{{ name }}, shop your favorites!{% else %}Shop your favorites!{% endif %}

Result (name = "Jon")

Jon, shop your favorites!

Result (name이 비어 있는 경우)

Shop your favorites!

문장 구조가 변경될 때는 default를 사용하지 마세요. 예를 들어, {{ name | default: "Shop your favorites" }}, shop your favorites는 name이 비어 있을 때 “Shop your favorites, shop your favorites”로 렌더링됩니다. 폴백이 변수 이상으로 변경된다면 if/else를 사용하세요.

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

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

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

사용자 생성 텍스트를 {% raw %} 및 {% endraw %}로 래핑하여 Liquid 구문 분석을 방지하세요. “raw” 구문을 참조하세요.

{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}

메시지 개인화

Liquid, Data Feeds 및 커스텀 이벤트를 포함한 모든 개인화 옵션 개요.

Data Feeds

전송 시 API에서 메시지로 실시간 데이터를 가져옵니다.

템플릿

Liquid 개인화가 내장된 재사용 가능한 메시지 템플릿을 만듭니다.

시작하기 & 설정

메시지 채널

Journeys

오디언스 & 사용자 지정 이벤트

분석 & 통합

개인 정보 보호 & 보안

Liquid 구문 사용

기본 구문

조건문

연산자

`if`, `elsif`, `else`

`unless`

필터

`default`

`date`

`capitalize`

`round`

`pluralize`

반복

`for` 루프

`limit` & `offset`

`where`

문자열 조작

자주 묻는 질문

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

`default`와 `if/else` 중 어떤 것을 사용해야 하나요?

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

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

관련 페이지

메시지 개인화

Data Feeds

태그

템플릿

시작하기 & 설정

메시지 채널

Journeys

오디언스 & 사용자 지정 이벤트

분석 & 통합

개인 정보 보호 & 보안

​기본 구문

​조건문

​연산자

​if, elsif, else

​unless

​필터

​default

​date

​capitalize

​round

​pluralize

​반복

​for 루프

​limit & offset

​where

​문자열 조작

​자주 묻는 질문

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

​default와 if/else 중 어떤 것을 사용해야 하나요?

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

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

​관련 페이지

메시지 개인화

Data Feeds

태그

템플릿

기본 구문

조건문

연산자

`if`, `elsif`, `else`

`unless`

필터

`default`

`date`

`capitalize`

`round`

`pluralize`

반복

`for` 루프

`limit` & `offset`

`where`

문자열 조작

자주 묻는 질문

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

`default`와 `if/else` 중 어떤 것을 사용해야 하나요?

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

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

관련 페이지