중첩 커스텀 속성

이 페이지에서는 중첩 커스텀 속성에 대해 설명하며, 이를 통해 속성 집합을 다른 속성의 등록정보로 정의할 수 있습니다. 즉, 커스텀 속성 오브젝트를 정의할 때 해당 오브젝트에 대한 추가 속성 집합을 정의할 수 있습니다.

중첩된 속성 정보

중첩 고객 속성을 사용하면 단일 커스텀 속성 오브젝트의 데이터로 더욱 풍부한 세그먼트를 구축하고 메시지를 개인화할 수 있습니다.

다음 예제에서 커스텀 속성 favorite_book 에는 중첩된 고객 속성 title, author, publishing_date 이 포함되어 있습니다. 이 개체를 사용하여 저자별로 사용자를 타겟팅하거나, 게시 날짜별로 필터링하거나, 책 제목을 메시지에 직접 삽입할 수 있습니다:

1
2
3
4
5
"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

Supported data types

다음 데이터 유형이 지원됩니다:

제한 사항

• 중첩 커스텀 속성은 Braze SDK 또는 API를 통해 전송된 커스텀 속성을 위한 것입니다.
• 오브젝트의 최대 크기는 100 KB입니다.
• 키 이름과 문자열 값의 크기 제한은 255자입니다.
• 키 이름에는 공백을 포함할 수 없습니다.
• 마침표(.)와 달러 기호($)는 중첩 커스텀 속성을 고객 프로필에 보내려는 경우 API 페이로드에서 지원되지 않는 문자입니다.
• 모든 Braze 파트너가 중첩 커스텀 속성을 지원하는 것은 아닙니다. 특정 파트너 통합에서 이 기능을 지원하는지 확인하려면 파트너 설명서를 참조하세요.
• 연결된 오디언스 API를 호출할 때 중첩 커스텀 속성을 필터로 사용할 수 없습니다.

API 예제

• create
• update
• delete

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "most_played_song": {
          "year_released": 1960
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
{"most_played_song": {
  "song_name": "Solea",
  "artist_name" : "Miles Davis",
  "album_name": "Sketches of Spain",
  "year_released": 1960,
  "genre": "Jazz",
  "play_analytics": {
     "count": 1000,
     "top_10_listeners": true
  }
}}

1
2
3
4
5
6
7
8
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

SDK 예제

• android sdk
• swift sdk
• web sdk

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
val json = JSONObject()
    .put("song_name", "Solea")
    .put("artist_name", "Miles Davis")
    .put("album_name", "Sketches of Spain")
    .put("genre", "Jazz")
    .put(
        "play_analytics",
        JSONObject()
            .put("count", 1000)
            .put("top_10_listeners", true)
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json)
}

1
2
3
4
5
6
val json = JSONObject()
    .put("year_released", 1960)

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json, true)
}

1
2
3
braze.getCurrentUser { user ->
    user.unsetCustomUserAttribute("most_played_song")
}

1
2
3
4
5
6
7
8
9
10
11
12
let json: [String: Any?] = [
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": [
    "count": 1000,
    "top_10_listeners": true,
  ],
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json)

1
2
3
4
5
let json: [String: Any?] = [
  "year_released": 1960
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json, merge: true)

1
braze.user.unsetCustomAttribute(key: "most_played_song")

1
2
3
4
5
6
7
8
9
10
11
12
import * as braze from "@braze/web-sdk";
const json = {
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": {
    "count": 1000,
    "top_10_listeners": true
  }
};
braze.getUser().setCustomUserAttribute("most_played_song", json);

1
2
3
4
5
6
import * as braze from "@braze/web-sdk";
const json = {
  "year_released": 1960
};
braze.getUser().setCustomUserAttribute("most_played_song", json, true);

1
2
import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);

오브젝트 등록정보로 날짜 캡처하기

오브젝트 등록정보로 날짜를 캡처하려면 $time 키를 사용해야 합니다. 다음 예제에서는 “중요 날짜” 오브젝트를 사용하여 오브젝트 등록정보 집합인 birthday 및 wedding_anniversary를 캡처합니다. 이 날짜의 값은 $time 키가 있는 오브젝트이며 null 값이 될 수 없습니다.

1
2
3
4
5
6
7
8
9
10
11
{
  "attributes": [ 
    {
      "external_id": "time_with_nca_test",
      "important_dates": {
        "birthday": {"$time" : "1980-01-01"},
        "wedding_anniversary": {"$time" : "2020-05-28"}
      }
    }
  ]
}

Liquid 템플릿

다음 Liquid 템플릿 예제에서는 앞의 API 요청에서 저장된 커스텀 속성 오브젝트 등록정보를 참조하여 메시징에 사용하는 방법을 보여줍니다.

custom_attribute 개인화 태그 및 점 표기법을 사용하여 오브젝트의 등록정보에 액세스합니다. 오브젝트 이름(오브젝트 배열을 참조하는 경우 배열 내 위치)과 점(마침표), 등록정보 이름을 차례로 지정합니다.

{{custom_attribute.${most_played_song}[0].artist_name}} — “Miles Davis”
{{custom_attribute.${most_played_song}[0].song_name}} — “Solea”
{{custom_attribute.${most_played_song}[0].play_analytics.count}} — “1000”

세분화

중첩 커스텀 속성을 기반으로 세그먼트를 구축하여 사용자를 더욱 세밀하게 타겟팅할 수 있습니다. 이렇게 하려면 커스텀 속성 오브젝트를 기준으로 세그먼트를 필터링한 다음 세분화할 등록정보 이름 및 관련 값의 경로를 지정합니다. 해당 경로가 어떻게 생겼는지 잘 모르겠다면 스키마를 생성하고 중첩 오브젝트 탐색기를 사용하여 Braze가 해당 경로를 채우도록 할 수 있습니다.

등록정보에 경로를 추가한 후 유효성 검사를 선택하여 경로 필드의 값이 유효한지 확인합니다.

중첩 커스텀 속성으로 세분화하려면 중첩 커스텀 속성 필터를 선택하여 특정 중첩 커스텀 속성을 선택할 수 있는 드롭다운을 표시합니다.

중첩 커스텀 속성 세분화로 작업할 때 데이터 유형별로 그룹화된 새로운 비교 연산자에 액세스할 수 있습니다. 예를 들어 play_analytics.count는 숫자이므로 숫자 카테고리에서 비교 연산자를 선택할 수 있습니다.

시간 데이터 유형 필터링

중첩된 시간 커스텀 속성을 필터링할 때 날짜 값을 비교할 때 연중 일자 또는 시간 카테고리의 연산자를 선택하여 필터링할 수 있습니다.

연중 일자 카테고리에서 연산자를 선택하면 중첩 커스텀 속성 값의 전체 타임스탬프 대신 월과 일만 비교됩니다. 시간 카테고리에서 연산자를 선택하면 연도를 포함한 전체 타임스탬프가 비교됩니다.

다중 기준 세분화

다중 기준 세분화를 사용하여 단일 오브젝트 내에서 여러 기준과 일치하는 세그먼트를 만들 수 있습니다. 이렇게 하면 지정된 모든 기준과 일치하는 오브젝트 배열이 하나 이상 있는 경우 사용자가 세그먼트에 포함됩니다. 예를 들어, 사용자는 키가 비어 있지 않고 숫자가 0보다 큰 경우에만 이 세그먼트와 일치합니다.

세그먼트에 대한 Liquid 복사 기능을 사용하여 이 세그먼트에 대한 Liquid 코드를 생성하고 이를 메시지에 사용할 수도 있습니다. 예를 들어 계정 오브젝트 배열과 활성 과세 대상 계정을 가진 고객을 타겟팅하는 세그먼트가 있다고 가정해 보겠습니다. 고객이 활성 및 과세 대상 계정 중 하나와 연결된 계정 목표에 기여하도록 유도하려면 넛지 메시지를 작성하는 것이 좋습니다.

세그먼트에 대해 Liquid 복사를 선택하면 Braze는 활성 상태이고 과세 대상인 계정만 포함된 오브젝트 배열을 반환하는 Liquid 코드를 자동으로 생성합니다.

1
2
3
4
5
6
7
{% assign segmented_nested_objects = '' | split: '' %}
{% assign obj_array = {{custom_attribute.${accounts}}} %}
{% for obj in obj_array %}
  {% if obj["account_type"] == 'taxable' and obj["active"] == true %}
    {% assign segmented_nested_objects = obj_array | slice: forloop.index0 | concat: segmented_nested_objects | reverse %}
  {% endif %}
{% endfor %}

여기에서 segmented_nested_objects를 사용하여 메시지를 개인화할 수 있습니다. 이 예에서는 첫 번째 활성 과세 대상 계정에서 목표를 가져와서 개인화하려고 합니다:

1
Get to your {{segmented_nested_objects[0].goal}} goal faster, make a deposit using our new fast deposit feature!

그러면 고객에게 다음과 같은 메시지가 반환됩니다: “Get to your retirement goal faster, make a deposit using our new fast deposit feature!”

중첩 오브젝트 탐색기를 사용하여 스키마 생성하기

중첩 오브젝트 경로를 외울 필요 없이 오브젝트에 대한 스키마를 생성하여 세그먼트 필터를 구축할 수 있습니다. 이렇게 하려면 다음 단계를 수행하세요.

1단계: 스키마 생성

이 예제에서는 방금 Braze로 전송한 accounts 오브젝트 배열이 있다고 가정합니다:

1
2
3
4
5
6
7
8
{"accounts": [
  {"type": "taxable",
  "balance": 22500,
  "active": true},
  {"type": "non-taxable",
  "balance": 0,
  "active": true}
]}

Braze 대시보드에서 데이터 설정 > 커스텀 속성으로 이동합니다.

오브젝트 또는 오브젝트 배열을 검색합니다. 속성 이름 열에서 스키마 생성을 선택합니다.

스키마가 생성되면 스키마 생성 버튼 대신 더하기 버튼이 새로 나타납니다. 클릭하면 이 중첩 커스텀 속성에 대해 Braze가 알고 있는 정보를 확인할 수 있습니다.

스키마를 생성하는 동안 Braze는 이전에 전송된 데이터를 살펴보고 이 속성에 대한 데이터의 이상적인 표현을 구축합니다. Braze는 중첩된 값에 대한 데이터 유형도 분석하여 추가합니다. 이는 주어진 중첩 속성에 대해 Braze로 전송된 이전 데이터를 샘플링하여 수행됩니다.

accounts 오브젝트 배열의 경우 오브젝트 배열 내에 다음이 포함된 오브젝트가 있음을 알 수 있습니다:

• 키가 active인 부울 유형(계정의 활성 여부에 관계없이)
• 키가 balance인 숫자 유형(계정의 잔액)
• 키가 type인 문자열 유형(비과세 또는 과세 계정)

이제 데이터를 분석하고 데이터 표현을 구축했으니 세그먼트를 만들어 보겠습니다.

2단계: 세그먼트 구축

잔액이 100 미만인 고객을 타겟팅하여 입금을 유도하는 메시지를 보내겠습니다.

세그먼트를 생성하고 필터 Nested Custom Attribute를 추가한 다음 오브젝트 또는 오브젝트 배열을 검색하고 선택합니다. 여기에 accounts 오브젝트 배열을 추가했습니다.

경로 필드에서 더하기 버튼을 선택합니다. 그러면 오브젝트 또는 오브젝트 배열의 표현이 나타납니다. 나열된 항목 중 원하는 항목을 선택하면 Braze가 경로 필드에 해당 항목을 삽입해 줍니다. 이 예제에서는 잔액을 가져와야 합니다. 잔액을 선택하면 경로(이 경우 [].balance)가 경로 필드에 자동으로 채워집니다.

유효성 검사를 선택하여 경로 필드의 콘텐츠가 유효한지 확인한 다음 필요에 따라 나머지 필터를 작성할 수 있습니다. 여기서는 잔액이 100 미만이어야 한다고 지정했습니다.

이것으로 끝입니다! 데이터 구조를 알 필요 없이 중첩 커스텀 속성을 사용하여 세그먼트를 만들었습니다. Braze의 중첩 오브젝트 탐색기가 데이터의 시각적 표현을 생성하고 세그먼트를 만드는 데 필요한 항목을 정확하게 탐색하고 선택할 수 있게 해줍니다.

중첩 커스텀 속성 변경 트리거

중첩 커스텀 속성 오브젝트가 변경될 때 트리거할 수 있습니다. 이 옵션은 오브젝트 배열의 변경에는 사용할 수 없습니다. 경로 탐색기를 볼 수 있는 옵션이 표시되지 않으면 스키마를 생성했는지 확인하세요.

예를 들어, 다음 동작 기반 캠페인에서 커스텀 속성 값 변경에 대한 새 트리거 동작을 추가하여 동네 사무실 기본 설정을 변경한 사용자를 타겟팅할 수 있습니다.

개인화

개인화 추가 모달을 사용하여 중첩 커스텀 속성을 메시지에 삽입할 수도 있습니다. 개인화 유형으로 중첩 커스텀 속성을 선택합니다. 다음으로 최상위 속성 및 속성 키를 선택합니다.

예를 들어 아래 개인화 모달에서는 사용자의 기본 설정에 따라 지역 동네 사무실의 중첩 커스텀 속성을 삽입합니다.

스키마 재생성

스키마가 생성된 후에는 24시간에 한 번씩 재생성할 수 있습니다. 이 섹션에서는 스키마를 재생성하는 방법에 대해 설명합니다. 스키마에 대한 자세한 내용은 이 문서의 스키마 생성 섹션을 참조하세요.

중첩 커스텀 속성에 대한 스키마를 재생성하려면:

1. 데이터 설정 > 커스텀 속성으로 이동합니다.
2. 중첩 커스텀 속성을 검색합니다.
3. 속성의 속성 이름 열에서 을 선택하여 스키마를 관리합니다.
4. 모달이 나타납니다. 스키마 재생성을 선택합니다.

스키마가 마지막으로 재생성된 후 24시간이 지나지 않은 경우 스키마 재생성 옵션이 비활성화됩니다. 스키마를 재생성하면 새 오브젝트만 감지되며 현재 스키마에 존재하는 오브젝트는 삭제되지 않습니다.

스키마를 재생성한 후 데이터가 예상대로 나타나지 않는다면 속성이 충분히 자주 수집되지 않은 것일 수 있습니다. 사용자 데이터는 주어진 중첩 속성에 대해 Braze로 전송된 이전 데이터에서 샘플링됩니다. 속성이 충분히 수집되지 않으면 스키마에 반영되지 않습니다.

오브젝트 배열을 사용한 세분화 동작

AND 로직으로 여러 Nested Custom Attribute 필터를 사용하여 오브젝트 배열을 세분화할 때, 각 필터는 배열의 모든 항목에 대해 독립적으로 평가됩니다. 배열의 어떤 항목이든 각 개별 필터를 충족하면 사용자가 세그먼트에 포함됩니다. 필터가 동일한 항목과 일치할 필요는 없습니다.

예를 들어, 사용자에게 다음과 같은 배열이 있다고 가정합니다:

1
2
3
4
5
6
{
  "orders": [
    {"product": "Shoes", "price": 80},
    {"product": "Hat", "price": 25}
  ]
}

다음 AND 필터가 있는 세그먼트:

• orders[].price가 50보다 큼
• orders[].price가 30보다 작음

이 사용자는 첫 번째 필터가 “Shoes” 항목(80 > 50)과 일치하고 두 번째 필터가 “Hat” 항목(25 < 30)과 일치하기 때문에 자격이 부여됩니다. 단일 항목이 두 조건을 모두 충족하지 않더라도 사용자는 여전히 세그먼트에 포함됩니다.

모든 조건이 배열 내 동일한 항목과 일치해야 하는 경우 동일한 경로에서 다중 기준 세분화를 사용하거나 교차 항목 매칭을 방지하도록 데이터를 재구성하세요.

데이터 포인트

전송되는 모든 키는 데이터 포인트를 소비합니다. 예를 들어, 고객 프로필에서 초기화된 이 오브젝트는 7개의 데이터 포인트로 계산됩니다:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "year_released": 1960,
        "genre": "Jazz",
        "play_analytics": {
          "count": 1000,
          "top_10_listeners": true
        }
      }
    }
  ]
}