콘텐츠로 건너뛰기

객체 태그 API (베타)

객체 태그는 사용자에 대한 구조화된 데이터를 하나의 태그에 저장합니다. Object 유형의 태그는 이름이 지정된 필드를 가진 객체 하나를 저장합니다. 예를 들어 amount와 status가 있는 마지막 order가 이에 해당합니다. ObjectList 유형의 태그는 이러한 객체의 배열을 저장합니다. 예를 들어 모든 orders가 이에 해당합니다. 필드 자체가 객체나 객체 목록일 수도 있습니다. 예를 들어 profile의 address가 이에 해당합니다. 필드는 한 번만 정의하면 되며, 태그 API를 통해 값을 쓰고 읽고, 필드 값으로 세그먼트를 만들고, Liquid로 메시지에 값을 삽입할 수 있습니다.

객체 태그의 작동 방식

Anchor link to

객체 태그에는 스키마와 값이 있습니다. 스키마는 태그 이름과 필드 목록이며, 각 필드는 고유한 유형을 가집니다. 값은 필드에 사용자별로 따로 저장됩니다.

  • 필드. 각 필드는 <object>.<field>라는 이름의 태그입니다(예: order.amount). 필드로 세그먼트를 만들 수 있으며, 이 이름으로 Object 태그의 필드를 쓸 수 있습니다.
  • Object 값. 사용자당 객체 하나입니다(예: "order": {"amount": 120, "status": "paid"}).
  • ObjectList 값. 동일한 필드를 가진 객체의 배열입니다(예: "orders": [{"amount": 120, "status": "paid"}, {"amount": 50}]).
  • 중첩 객체. 자체 필드를 가진 OBJECT 유형의 필드입니다(예: profile.address.city 필드가 있는 profile.address).
  • 중첩 목록. OBJECT_LIST 유형의 필드로, 객체 태그 내부의 객체 배열입니다(예: profile.visits). 중첩 객체 및 목록을 참조하세요.

API에서 태그 및 필드 유형은 OBJECT와 OBJECT_LIST입니다. Control Panel에서는 객체와 객체 목록입니다. 이 페이지에서 객체 목록은 ObjectList 태그 또는 중첩 목록을 의미합니다.

객체 태그는 항상 User-specific 태그입니다. 즉, 값은 단일 디바이스가 아닌 사용자에게 속하며 해당 사용자의 모든 디바이스에 복사됩니다. 일반 태그에 대해서는 태그 API를 참조하세요.

중첩 객체 및 목록

Anchor link to

객체 태그의 필드는 단일 값 대신 자체 필드를 가질 수 있습니다. OBJECT 유형의 필드인 중첩 객체는 객체 하나를 저장합니다. OBJECT_LIST 유형의 필드인 중첩 목록은 객체 목록을 저장합니다. 목록의 요소에도 중첩 객체와 중첩 목록이 포함될 수 있습니다. 각 필드는 profile.address.city와 같이 점으로 구분된 전체 이름을 유지하며, 이 이름으로 세그먼트를 만듭니다.

예를 들어 OBJECT 유형의 profile 태그와 OBJECT_LIST 유형의 orders 태그는 다음과 같은 구조를 가질 수 있습니다.

profile OBJECT
├── address OBJECT
│ ├── city STRING
│ └── geo OBJECT
│ └── lat STRING
└── visits OBJECT_LIST
└── code STRING
orders OBJECT_LIST
├── sku STRING
├── meta OBJECT
│ └── color STRING
└── lines OBJECT_LIST
└── qty INTEGER

검색 가능한 필드와 저장 전용 필드

Anchor link to

필드로 할 수 있는 작업은 필드 상위에 있는 객체 목록의 수에 따라 달라집니다.

  • 필드 상위에 목록이 없음. profile.address.city와 같은 필드로 세그먼트를 만들고, 전체 이름으로 해당 필드만 따로 쓰고, 메시지에 사용할 수 있습니다.
  • 필드 상위에 목록이 하나 있음. profile.visits.code 또는 orders.meta.color와 같은 필드로 세그먼트를 만들고 메시지에 사용할 수 있습니다. 쓰기는 전체 목록의 일부로만 가능합니다.
  • 필드 상위에 목록이 두 개 있음. orders.lines.qty와 같은 필드는 저장 전용입니다. 메시지에는 사용할 수 있지만 세그먼트에는 사용할 수 없습니다.

Pushwoosh는 중첩 객체와 중첩 목록을 포함한 객체 태그에 다음 제한을 적용합니다.

제한값초과 시
중첩 깊이객체와 목록 3단계. 태그 자체가 첫 번째 단계이므로 profile.address.geo가 허용되는 가장 깊은 객체입니다스키마 메서드가 HTTP 400을 반환합니다. 오류를 참조하세요
객체 하나의 필드 수태그와 각 중첩 객체 또는 중첩 목록마다 1~20개스키마 메서드가 HTTP 400을 반환합니다. 오류를 참조하세요
객체 태그 하나에서 값을 가진 필드 수중첩 필드를 포함하여 50개. OBJECT 및 OBJECT_LIST 유형의 필드는 포함되지 않습니다스키마 메서드가 HTTP 400을 반환합니다. 오류를 참조하세요
전체 필드 이름64자(예: profile.address.city)스키마 메서드가 HTTP 400을 반환합니다. 오류를 참조하세요
객체 목록 하나의 요소 수태그와 각 중첩 목록마다 100개쓴 값 전체가 거부됩니다
쓴 값 하나의 크기JSON 64KB쓴 값 전체가 거부됩니다

거부된 값은 필드 유형이 잘못된 값과 같은 방식으로 처리됩니다. 쓰기는 전체 값을 대체합니다를 참조하세요.

스키마 규칙

Anchor link to

객체 태그를 생성하거나 필드를 추가할 때 Pushwoosh는 다음 규칙을 확인합니다.

  • 객체 이름과 필드 이름에는 라틴 문자, 숫자, _만 사용할 수 있습니다.
  • 태그와 각 중첩 객체 또는 중첩 목록에는 1~20개의 필드가 있습니다. 다른 제한도 적용됩니다. 필드 이름은 대소문자를 구분하지 않으므로 Amount와 amount는 같은 필드입니다.
  • 필드 유형은 INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT, OBJECT_LIST 중 하나입니다. OBJECT 또는 OBJECT_LIST 유형의 필드에는 자체 fields가 필요합니다. 시간대 필드는 지원되지 않습니다.
  • 필드에는 다른 태그가 이미 사용 중인 이름을 지정할 수 없습니다. order.note 태그가 있으면 order에 note 필드를 추가할 때 tag order.note already exists로 실패합니다.
  • 객체의 마지막 필드는 삭제할 수 없습니다. 대신 객체를 삭제하세요.
  • 사용 중인 필드나 객체 태그는 삭제할 수 없습니다. 중첩 객체나 중첩 목록은 내부의 항목이 하나라도 사용 중이면 사용 중으로 간주됩니다. 오류에는 사용 위치가 나열됩니다(예: field is in use: segment Big buyers, in-app Spring sale). 태그를 참조하는 세그먼트, 인앱, 실행 중인 Customer Journey 캠페인, 프리셋, 이메일 템플릿 및 기타 항목이 사용으로 간주됩니다.

Control Panel에서 객체 태그 관리

Anchor link to

Control Panel에서 중첩 객체와 중첩 목록이 없는 객체 태그를 생성합니다.

  1. Control Panel의 태그 페이지에서 태그 생성을 클릭합니다.
  2. 태그 이름을 입력합니다.
  3. 값 유형에서 객체 또는 객체 목록을 선택합니다.
  4. 필드 아래에 첫 번째 필드의 이름을 입력합니다.
  5. 필드 유형을 선택합니다.
  6. 필드를 더 추가하려면 필드 추가를 클릭합니다.
  7. 생성을 클릭합니다.

태그 페이지에서 필드를 추가하거나, 필드 옆의 삭제를 클릭하여 필드를 삭제할 수 있습니다. Control Panel에서는 중첩 객체나 중첩 목록을 생성하거나 그 필드를 변경할 수 없습니다. API로 생성한 중첩 객체나 중첩 목록은 객체 또는 객체 목록 유형의 필드 하나로 표시됩니다. 이 필드를 삭제하면 내부의 모든 항목과 함께 삭제됩니다.

스키마 관리

Anchor link to

아래 REST 메서드로 객체 태그를 생성하고 변경합니다. /json/1.3/addTag는 필드를 정의할 수 없으므로 일반 태그에만 사용하세요.

기본 URL

Anchor link to
https://rpc-api.svc-nue.pushwoosh.com

모든 요청에는 서버 API 토큰이 포함된 Authorization 헤더가 있어야 합니다. 디바이스 API 토큰을 사용하면 HTTP 403 a device API token cannot call this method, use an account API token이 반환됩니다.

Authorization: Api YOUR_API_TOKEN

엔드포인트

Anchor link to

다음 메서드로 객체 태그의 스키마를 관리하고 필드 값을 읽습니다.

메서드경로설명
POST/api/tags필드와 함께 객체 태그 생성
GET/api/tags/{name}필드와 함께 객체 태그 가져오기
GET/api/tags태그 목록 조회. 객체 태그는 중첩 필드를 포함한 모든 fields와 함께 반환되며, 필드는 별도의 태그로 나열되지 않음
POST/api/tags/{name}/fields객체 태그, 중첩 객체 또는 중첩 목록에 필드 추가
DELETE/api/tags/{name}/fields/{field}필드, 중첩 객체 또는 중첩 목록 삭제
DELETE/api/tags/{name}모든 필드와 함께 객체 태그 삭제
GET/api/tags:values필드에 저장된 값 목록 조회. 필드에 저장된 값 참조

POST /api/tags는 객체 태그를 반환하고, 두 필드 메서드는 변경 후 {name}에 지정된 객체를 반환하며, 둘 다 {"tag": {...}}로 감싸서 반환합니다. DELETE /api/tags/{name}은 {}를 반환합니다.

계정에서 객체 태그가 활성화되지 않은 경우, 객체 유형으로 호출한 POST /api/tags와 두 필드 메서드는 HTTP 403 object tags are not enabled for the account로 실패합니다. GET /api/tags/{name}과 DELETE /api/tags/{name}은 HTTP 404 tag not found를 반환하며, GET /api/tags는 객체 태그를 나열하지 않습니다. 객체 태그가 활성화되지 않으면 객체 태그를 생성할 수 없으므로 값을 쓸 대상도 없습니다.

객체 태그 생성

Anchor link to

POST /api/tags

요청 본문
Anchor link to
이름유형설명
name*string객체 태그의 이름입니다.
type*string객체 하나는 OBJECT, 객체 목록은 OBJECT_LIST입니다.
fields*array객체의 필드이며, 1~20개입니다.
fields[].name*string필드 이름입니다. 필드는 <name>.<fields[].name> 태그가 됩니다.
fields[].type*string필드 유형: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT 또는 OBJECT_LIST.
fields[].fieldsarray중첩 객체 또는 중첩 목록의 필드이며, 같은 형식으로 1~20개입니다. OBJECT 및 OBJECT_LIST 유형에는 필수이며 다른 유형에서는 무시됩니다.
예시
{
"name": "orders",
"type": "OBJECT_LIST",
"fields": [
{ "name": "amount", "type": "INTEGER" },
{ "name": "status", "type": "STRING" }
]
}
응답
{
"tag": {
"name": "orders",
"type": "OBJECT_LIST",
"system": false,
"user_specific": true,
"has_right_ace_modify": true,
"fields": [
{ "name": "amount", "type": "INTEGER", "fields": [] },
{ "name": "status", "type": "STRING", "fields": [] }
]
}
}

태그는 user_specific 값과 관계없이 User-specific 태그로 생성됩니다. GET /api/tags/{name}은 tag 래퍼 없이 같은 객체를 반환합니다. 필드는 이름순으로 정렬되며, 중첩 필드가 없는 필드는 빈 fields 배열과 함께 반환됩니다.

중첩 객체와 중첩 목록을 생성하려면 필드에 OBJECT 또는 OBJECT_LIST 유형과 자체 fields를 지정합니다. 요청 하나로 전체 구조가 생성됩니다.

예시: 중첩 객체 및 목록의 profile 태그
{
"name": "profile",
"type": "OBJECT",
"fields": [
{
"name": "address",
"type": "OBJECT",
"fields": [
{ "name": "city", "type": "STRING" },
{ "name": "geo", "type": "OBJECT", "fields": [{ "name": "lat", "type": "STRING" }] }
]
},
{
"name": "visits",
"type": "OBJECT_LIST",
"fields": [{ "name": "code", "type": "STRING" }]
}
]
}

중첩 필드는 address 안의 city처럼 해당 객체 기준의 상대 이름으로 반환됩니다. GET /api/tags/{name}은 태그 자체의 이름만 받습니다. profile.address와 같은 중첩 이름은 HTTP 404 tag not found를 반환합니다.

필드 추가

Anchor link to

POST /api/tags/{name}/fields

예시: POST /api/tags/orders/fields
{
"field": { "name": "note", "type": "STRING" }
}

중첩 객체나 중첩 목록에 필드를 추가하려면 {name}에 전체 이름을 지정합니다(예: POST /api/tags/profile.address/fields 또는 POST /api/tags/profile.visits/fields). 새 필드는 자체 fields를 가진 중첩 객체나 중첩 목록일 수 있습니다.

예시: POST /api/tags/profile/fields
{
"field": {
"name": "company",
"type": "OBJECT",
"fields": [{ "name": "title", "type": "STRING" }]
}
}

새 필드는 전체 태그 값의 일부로 바로 쓸 수 있습니다. 객체에 이미 필드가 20개 있거나, 필드가 다른 제한을 위반하거나, 전체 필드 이름과 같은 태그가 있으면 필드 추가가 실패합니다. 오류를 참조하세요.

필드 삭제

Anchor link to

DELETE /api/tags/{name}/fields/{field}

예를 들어 DELETE /api/tags/orders/fields/note는 orders.note 필드를 삭제합니다. 중첩 객체나 중첩 목록의 필드를 삭제하려면 {name}에 전체 이름을 지정합니다: DELETE /api/tags/profile.address/fields/city.

중첩 객체나 중첩 목록을 삭제하면 내부의 모든 항목이 삭제됩니다. DELETE /api/tags/profile/fields/address는 profile.address.city와 profile.address.geo도 삭제합니다. 객체의 마지막 필드, 또는 사용 중인 필드, 중첩 객체, 중첩 목록은 삭제할 수 없습니다. 오류를 참조하세요.

오류는 {"code": <n>, "message": "...", "details": [...]} 형식으로 반환됩니다. 객체 태그를 생성할 때 400 메시지는 validate: rpc error: code = InvalidArgument desc = <message> 형식이며, 여기서 <message>는 표의 텍스트입니다. 이 메시지에서 <object>는 profile.address와 같은 객체의 전체 이름입니다.

HTTP 상태메시지원인
400object tag and field names must contain only letters, digits and underscores이름에 다른 문자가 포함되어 있습니다.
400<object>: an object needs 1 to 20 fields생성 시 태그, 중첩 객체 또는 중첩 목록에 필드가 없거나 20개를 초과합니다.
400an object has at most 20 fields필드를 추가하려는 객체에 이미 필드가 20개 있습니다.
400<object>.<field>: objects nest at most 3 levels deepOBJECT 또는 OBJECT_LIST 필드가 네 번째 단계가 됩니다.
400an object tag holds at most 50 fields with values, nested ones included객체 태그에서 값을 가진 필드가 50개를 초과합니다.
400field <name> is given twice대소문자를 무시하면 두 필드의 이름이 같습니다.
400<object>.<field>: object and field names together cannot be longer than 64 characters전체 필드 이름이 너무 깁니다.
400<object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LIST지원되지 않는 필드 유형입니다.
400an object needs at least one field; delete the object instead객체의 마지막 필드를 삭제하려고 했습니다.
400field is in use: ..., tag is in use: ...필드, 중첩 객체나 중첩 목록 내부의 항목, 또는 객체 태그가 세그먼트, 인앱, Customer Journey 캠페인 또는 기타 항목에서 사용 중입니다.
403object tags are not enabled for the account계정에서 객체 태그가 활성화되지 않았습니다.
403a device API token cannot call this method, use an account API token요청에 디바이스 API 토큰을 사용했습니다.
404tag not foundGET 또는 DELETE /api/tags/{name}: 해당 태그가 없거나, 이름이 필드이거나, 객체 태그가 활성화되지 않았습니다.
404object tag not found, field not found필드 메서드: 해당 객체 태그, 중첩 객체, 중첩 목록 또는 필드가 없습니다. 값을 가진 필드를 {name}에 지정해도 object tag not found가 반환됩니다.
409tag already exists객체 태그 이름과 같은 태그가 있습니다.
409tag <object>.<field> already exists필드의 전체 이름과 같은 태그가 있습니다.

값 쓰기

Anchor link to

/setTags와 /bulkSetTags로 객체 태그 값을 씁니다. 이 메서드들은 자체 인증 방식을 유지합니다. /setTags는 Authorization: Token 헤더에 디바이스 API 토큰을 받고, /bulkSetTags는 auth에 API 액세스 토큰을 받습니다. Object 값은 JSON 객체로, ObjectList 값은 객체 배열로 보냅니다.

예시: /json/1.3/setTags
{
"request": {
"application": "XXXXX-XXXXX",
"userId": "user_42",
"tags": {
"order": { "amount": 120, "status": "paid" },
"orders": [
{ "amount": 120, "status": "paid" },
{ "amount": 50 }
]
}
}
}

HWID로 값을 설정하면 해당 디바이스의 사용자에게 저장됩니다. 스키마 메서드의 기본 URL에 있는 POST /api/devices:set_tags도 같은 규칙으로 객체 태그를 씁니다. 이 메서드의 응답에는 객체의 필드가 "profile.address.city"와 같은 평면 이름으로 나열됩니다.

중첩 객체는 JSON 객체를, 중첩 목록은 객체 배열을 받습니다.

예시: /json/1.3/setTags의 중첩 값
"tags": {
"profile": {
"address": { "city": "Berlin", "geo": { "lat": "52.5" } },
"visits": [{ "code": "v1" }]
},
"orders": [
{ "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] }
]
}

각 필드는 해당 유형 형식의 값을 받습니다.

필드 유형값 예시
INTEGER120
STRING"paid"
LIST["gift", "express"]
DATE"2026-10-02 22:11"(UTC), "2026-10-02" 또는 초 단위 Unix 타임스탬프
BOOLEANtrue 또는 false
PRICE19.95
VERSION"1.0.0"

쓰기는 전체 값을 대체합니다

Anchor link to

쓸 때마다 객체 태그에 저장된 값이 대체됩니다.

  • 새 값에 없는 필드는 삭제됩니다. null로 보낸 필드도 삭제됩니다.
  • null, [] 또는 ""는 전체 값을 삭제합니다.
  • {}는 Object 태그의 모든 필드를 삭제합니다.
  • 객체의 필드가 아닌 키는 건너뜁니다.
  • 어느 깊이에서든 필드 값이 필드 유형과 일치하지 않으면 태그의 전체 값이 거부되고 저장된 값은 그대로 유지됩니다. 값이 제한을 위반하는 경우(요소가 100개를 초과하는 목록 또는 JSON 64KB 초과)에도 마찬가지입니다.

/setTags는 거부된 값을 응답에서 알려주지 않으며 HTTP 200을 반환합니다. /getTags로 결과를 확인하거나, 태그별 결과를 알려주는 /bulkSetTags를 사용하세요.

숨김 필드

Anchor link to

숨김 필드는 Pushwoosh가 자체 용도로 숨김 처리한 필드입니다. 이 페이지의 스키마 메서드로는 필드를 생성하거나 숨길 수 없습니다. /getTags는 숨김 필드를 반환하지 않으므로, 읽은 값을 다시 써도 숨김 필드는 포함되지 않습니다. 쓰기 시 숨김 필드가 어떻게 처리되는지는 유형에 따라 다릅니다.

  • Object. 새 값에 없는 숨김 필드는 어느 깊이에서든 유지됩니다. 새 값에 없는 표시되는 중첩 객체는 숨김 필드를 포함하여 내부의 모든 항목과 함께 삭제됩니다. 전체 값을 삭제하면 숨김 필드도 삭제됩니다.
  • ObjectList. 목록을 쓰면 모든 요소가 대체되며, 이전 요소의 숨김 필드는 사라집니다. 요소에는 식별자가 없으므로 새 요소를 이전 요소와 대응시킬 수 없습니다. 중첩 목록에도 같은 규칙이 적용됩니다.

Object의 일부 쓰기

Anchor link to

전체 태그 값 대신 Object 태그의 필드 하나, 중첩 객체 또는 중첩 목록을 전체 이름으로 씁니다. increment와 /setTags의 다른 연산은 필드에서도 작동합니다.

"tags": {
"order.status": "shipped",
"order.amount": { "operation": "increment", "value": 5 }
}

상위에 객체만 있는 중첩 객체의 필드도 같은 방식으로 쓸 수 있습니다(예: "profile.address.city": "Paris").

상위에 객체만 있는 중첩 객체나 중첩 목록은 profile.address 또는 profile.visits와 같은 전체 이름으로 따로 쓸 수 있습니다. 이 값은 해당 항목만 대체하며 profile의 나머지는 그대로 유지됩니다. 요소 100개 및 64KB 제한은 이 값을 기준으로 계산됩니다.

"tags": {
"profile.address": { "city": "Paris" },
"profile.visits": [{ "code": "v2" }]
}

객체 목록 내부의 항목은 어떤 요소를 변경할지 명확하지 않으므로 따로 쓸 수 없습니다. 여기에는 orders.sku와 같은 ObjectList 태그의 필드와, orders.meta 또는 profile.visits.code와 같은 요소 내부의 모든 항목이 포함됩니다. /setTags는 이러한 값을 건너뜁니다. 대신 전체 목록을 보내세요.

객체 태그는 자동으로 생성되지 않습니다

Anchor link to

존재하지 않는 태그에 대한 객체 또는 객체 배열 값은 건너뜁니다. 태그 자동 생성은 객체 태그를 생성하지 않으므로 먼저 POST /api/tags로 스키마를 생성하세요.

bulkSetTags 결과

Anchor link to

detailed=true를 사용하면 /bulkSetTags 상태는 ok, tag not found, wrong value. expect :<type> 외에 객체 태그에 대해 다음 결과 중 하나를 반환합니다.

결과원인
object tags are stored on the user only객체 태그가 User-specific 태그가 아닙니다.
cannot load the fields of the objectPushwoosh가 객체 태그의 필드를 읽을 수 없습니다.
wrong value. expect an object (a map) or, for a list of objects, an array of maps값이 객체 태그에 맞지 않거나, 어느 깊이에서든 필드 값이 해당 유형과 일치하지 않거나, 값이 제한을 위반합니다.
a field of a list of objects cannot be set on its own, set the whole listorders.sku 또는 orders.meta와 같은 객체 목록 내부의 항목에 값을 설정했습니다.

값 읽기

Anchor link to

/getTags는 Object 값을 JSON 객체로, ObjectList 값을 객체 배열로 반환합니다.

응답
{
"status_code": 200,
"status_message": "OK",
"response": {
"result": {
"order": { "amount": 120, "status": "paid" },
"orders": [
{ "amount": 120, "status": "paid" },
{ "amount": 50 }
]
}
}
}

중첩 객체와 중첩 목록은 어느 깊이에서든 쓸 때와 같은 형태로 반환됩니다(예: "profile": {"address": {"city": "Berlin"}, "visits": [{"code": "v1"}]}).

필드 값은 /getTags의 일반 태그 값과 같은 방식으로 반환됩니다. Date는 초 단위 Unix 타임스탬프로, Price는 "120.00"과 같은 문자열로, Boolean은 1 또는 0으로 반환됩니다.

필드에 저장된 값

Anchor link to

기본 URL의 GET /api/tags:values는 필드가 가진 고유 값을 값별 구독자 수와 함께 나열합니다. name에 필드의 전체 이름(예: profile.address.city 또는 orders.sku)을 전달합니다.

쿼리 매개변수
Anchor link to
이름유형설명
application*string애플리케이션 코드, XXXXX-XXXXX입니다.
name*string필드의 전체 이름입니다.
likestringlike_op로 지정한 위치에 이 텍스트가 포함된 값만 반환합니다.
like_opstringSTARTS_WITH(기본값), ENDS_WITH 또는 CONTAINS입니다.
order_bystringVALUE(기본값) 또는 COUNT입니다.
order_directionstringASC(기본값) 또는 DESC입니다.
limitinteger반환할 값의 수입니다. 기본값은 100입니다.
offsetinteger건너뛸 값의 수입니다.
pageinteger0부터 시작하는 페이지 번호입니다. limit 및 offset 대신 per_page와 함께 사용합니다.
per_pageinteger한 페이지의 값 수입니다.
예시
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC
응답
{
"values": [
{ "value": "A-1", "count": 120 },
{ "value": "B-2", "count": 45 }
],
"total": 2,
"page": 0,
"per_page": 100
}

Integer 및 Price 필드는 같은 유형의 일반 태그와 마찬가지로 값을 반환하지 않습니다. 객체 태그, 중첩 객체 또는 중첩 목록 자체에는 고유한 값이 없으므로, 해당 이름으로 요청하면 HTTP 404 tag not found가 반환됩니다.

필드로 세그먼트 만들기

Anchor link to

세그먼트 조건은 객체 태그 자체가 아니라 필드에 설정합니다. 세분화 언어에서 필드는 이름에 점이 포함된 태그이며, 자체 유형의 연산자를 사용합니다.

AT("XXXXX-XXXXX", "order.amount", gte, 100)

중첩 객체나 중첩 목록의 필드는 profile.address.city, profile.visits.code 또는 orders.meta.color와 같은 전체 이름을 사용합니다. 객체 태그 자체, 중첩 객체 또는 중첩 목록(예: profile.address)에 대한 조건은 object tag has no value of its own, use one of its fields로 실패합니다.

orders.lines.qty와 같이 상위에 객체 목록이 두 개 있는 필드는 저장 전용입니다. 이러한 조건이 있는 세그먼트는 저장되지만, 세그먼트를 계산하거나 해당 세그먼트로 전송하면 a field inside a list nested in a list is stored only and cannot be searched로 실패합니다.

ObjectList에 대한 조건

Anchor link to

ObjectList 태그의 필드에 대한 조건은 목록의 요소 중 하나 이상이 조건에 맞으면 사용자와 일치합니다. AND로 연결된 같은 목록의 필드 조건은 같은 요소와 일치해야 합니다.

AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")

이 세그먼트에는 100 이상이면서 결제된 주문이 하나 이상 있는 사용자가 포함됩니다. 결제되지 않은 큰 주문 하나와 결제된 작은 주문 하나가 있는 사용자는 일치하지 않습니다. 요소 내부 객체의 필드에도 같은 요소가 확인됩니다. orders.sku가 A-1과 같음 AND orders.meta.color가 red와 같음 조건은 두 값을 모두 가진 주문이 하나 있는 사용자와 일치합니다. OR로 연결된 조건은 같은 요소와 일치할 필요가 없습니다. 서로 다른 두 목록에 대한 조건은 각 목록에서 따로 확인됩니다.

일부 연산자는 ObjectList 태그의 필드에서 다르게 작동합니다.

  • notset. 목록의 어떤 요소도 이 필드에 값이 없습니다. 목록이 없는 사용자도 일치합니다.
  • noteq. 하나 이상의 요소가 이 필드에 값이 있고, 그 값이 지정된 값과 다릅니다. 필드가 없는 요소는 고려되지 않습니다. 상태가 paid와 new인 주문이 있는 사용자는 noteq "paid"와 일치합니다.
  • List 필드의 notin. 지정된 값 중 어느 것도 포함하는 요소가 없습니다.
  • 다른 유형 필드의 notin. 하나 이상의 요소가 이 필드에 지정된 값에 속하지 않는 값을 가집니다.

notset과 List 필드의 notin은 AND로 연결된 다른 조건과 같은 요소에 묶이지 않습니다. 이 규칙은 profile.visits와 같은 중첩 목록에도 적용됩니다.

메시지에 값 사용

Anchor link to

Liquid 템플릿으로 객체 태그의 필드를 푸시 알림, 이메일, SMS, WhatsApp과 같은 메신저 메시지에 삽입합니다. Liquid는 계정에서 콘텐츠 템플릿이 활성화된 경우에만 작동합니다. 어느 깊이에서든 필드를 전체 이름으로 씁니다.

Your city is {{ profile.address.city }}.

객체 목록의 요소는 0부터 시작하는 인덱스로 가져옵니다.

Your first order is {{ orders[0].sku }}, quantity {{ orders[0].lines[0].qty }}.

인덱스가 목록의 끝을 넘거나 사용자에게 해당 목록이 없으면 빈 문자열로 렌더링됩니다. 먼저 요소를 확인하거나 default로 대체 값을 설정하세요.

{% if orders[0] %}Your first order is {{ orders[0].sku }}.{% endif %}
Your first order is {{ orders[0].sku | default: "on its way" }}.

요소 내부의 목록을 포함하여 객체 목록을 반복합니다.

{% for o in orders %}{{ o.meta.color }}{% for l in o.lines %}{{ l.qty }}{% endfor %}{% endfor %}

orders.lines.qty와 같은 저장 전용 필드도 템플릿에서 다른 필드와 같은 방식으로 작동합니다.

객체 태그가 포함된 세그먼트 내보내기

Anchor link to

/exportSegment는 객체 태그의 필드를 내보냅니다.

  • CSV. 값이 있는 각 필드는 order.amount 또는 profile.address.city와 같은 전체 이름의 별도 열입니다. 객체 태그, 중첩 객체, 중첩 목록 자체에는 열이 없습니다. 어느 깊이에서든 객체 목록 내부의 필드는 List 태그와 같은 방식으로 모든 요소의 고유 값을 JSON 배열로 담습니다: ["A-1","B-2"]. 배열은 정렬되어 있고 값이 어느 요소에서 왔는지 보여주지 않으므로 요소의 순서도 유지되지 않습니다. 요소를 통째로 가져오려면 json 또는 json_each_line으로 내보내세요.
  • json 및 json_each_line. 객체 태그는 /getTags가 반환하는 것과 같은 형태로 중첩되어 제공됩니다. Object 태그는 tags의 항목 하나이며 필드는 object.fields 아래에 있고, 그 안의 중첩 객체도 모든 수준에서 자체 필드를 object.fields 아래에 담습니다. ObjectList 태그는 요소가 object_list.items에 있는 항목 하나이며, 중첩 목록도 마찬가지입니다. 필드는 짧은 이름을 사용하고 이름순으로 정렬되며, 유형 이름을 딴 키 아래에 값을 담습니다: integer, string, list, date, boolean, price 또는 version.
{
"name": "profile",
"object": {
"fields": [
{ "name": "address", "object": { "fields": [{ "name": "city", "string": "Berlin" }] } },
{ "name": "visits", "object_list": { "items": [{ "fields": [{ "name": "code", "string": "v1" }] }] } }
]
}
}

ObjectList 태그는 다음과 같습니다. 정수 값은 문자열로 제공됩니다.

{
"name": "orders",
"object_list": {
"items": [
{ "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] },
{ "fields": [{ "name": "amount", "integer": "50" }] }
]
}
}

중첩 객체와 중첩 목록이 있는 요소는 다음과 같습니다.

{
"fields": [
{ "name": "meta", "object": { "fields": [{ "name": "color", "string": "red" }] } },
{ "name": "lines", "object_list": { "items": [{ "fields": [{ "name": "qty", "integer": "2" }] }] } }
]
}

tagsList에 객체 태그를 지정하면 중첩 필드를 포함하여 해당 태그의 모든 필드를 내보냅니다.