콘텐츠로 건너뛰기

키-값 페어

이 페이지에서는 키-값 페어를 사용하여 사용자 기기에 추가 데이터 페이로드를 전송하는 방법을 다룹니다. 이 기능은 푸시, 인앱, 이메일 및 Content Cards 메시징 채널에서 사용할 수 있습니다.

키-값 페어를 사용하여 메시지에 구조화된 메타데이터를 추가할 수 있습니다. 이러한 추가 데이터 페이로드는 메시지가 렌더링되거나 처리되는 방식에 영향을 줄 수 있는 추가 상황별 정보로 메시지를 더욱 풍부하게 만들 수 있습니다.

키-값 페어는 메타데이터이므로 이 데이터가 반드시 수신자에게 표시되는 것은 아니지만, 연결된 시스템이나 프로세스에서 메시지 처리를 커스터마이즈하는 데 사용할 수 있습니다.

각 페어는 다음으로 구성됩니다:

  • 키: 식별자 (예: utm_source)
  • 값: 연결된 데이터 (예: newsletter)

사용 사례

다음은 키-값 페어로 메타데이터를 추가하는 사용 사례의 예시입니다.

  1. 추적 매개변수: 분석 목적으로 UTM 매개변수 첨부
    • 키: utm_campaign
    • 값: spring_sale
  2. 커스텀 태그: 내부 라우팅 또는 분류를 위한 태그 추가
    • 키: priority
    • 값: high
  3. 동작 트리거: 인앱 동작을 트리거하거나 커스터마이징하는 데 사용되는 메타데이터
    • 키: deep_link
    • 값: app://promo-page

푸시 알림

Android, iOS 및 웹 푸시 알림에 키-값 페어를 추가할 수 있습니다. 키-값 페어로 내부 측정기준과 앱 콘텐츠를 업데이트할 수 있습니다. 알림 우선순위, 현지화, 사운드 같은 푸시 알림 속성을 커스텀하는 데도 사용할 수 있습니다.

메시지 작성기에서 설정 탭을 선택하고 새 페어 추가를 선택한 다음 키-값 페어를 지정합니다.

메시지 작성기에서 추가한 키-값 페어의 값은 문자열로 전송됩니다. iOS 푸시의 경우, 알림 옵션에서 추가하는 예약된 Apple 푸시 알림 서비스(APNs) 알림 키(예: 현지화 인수를 위한 loc-args)는 페이로드에서 올바른 JSON 유형으로 형식이 지정됩니다. 커스텀 키는 통합에서 따로 파싱하지 않으면 앱이 문자열 값으로 받습니다.

iOS

Apple 푸시 알림 서비스(APNs)는 키-값 페어를 사용하여 알림 환경설정을 지정하고 커스텀 데이터를 전송하는 기능을 지원합니다. APNs는 Apple이 예약한 aps 라이브러리를 사용합니다. 이 라이브러리에는 알림 속성을 제어하는 미리 정해진 키와 값이 포함되어 있습니다.

APS 라이브러리

키 값 유형 값 설명
alert 문자열 또는 사전 오브젝트 문자열을 입력하면 해당 문자열을 메시지로 하고 닫기 및 보기 버튼이 있는 알림을 표시합니다. 문자열이 아닌 값을 입력하면 입력값의 하위 속성에 따라 알림 또는 배너를 표시합니다
badge 숫자 앱 아이콘에 배지로 표시되는 숫자를 제어합니다
sound 문자열 알림으로 재생할 사운드 파일의 이름입니다. 앱 번들 또는 Library/Sounds 폴더에 있어야 합니다
content-available 숫자 입력값이 1이면 앱 실행 또는 세션 재개 시 새로운 정보가 있음을 앱에 알립니다
알림 속성 라이브러리
키 값 유형 값 설명
title 문자열 Apple Watch가 알림의 일부로 잠시 표시하는 짧은 문자열입니다
body 문자열 푸시 알림의 콘텐츠입니다
title-loc-key 문자열 또는 null Localizable.strings 파일에서 현재 현지화에 맞는 제목 문자열을 설정하는 키입니다
title-loc-args 문자열 배열 또는 null title-loc-key의 제목 현지화 형식 지정자 대신 표시될 수 있는 문자열 값입니다
action-loc-key 문자열 배열 또는 null 지정된 경우, 해당 문자열이 닫기 및 보기 버튼의 현지화를 설정합니다
loc-key 문자열 또는 null Localizable.strings 파일에서 현재 현지화에 맞는 알림 메시지를 설정하는 키입니다
loc-args 문자열 배열 loc-key의 현지화 형식 지정자 대신 표시될 수 있는 문자열 값입니다
launch-image 문자열 사용자가 실행 버튼을 탭하거나 실행 슬라이더를 움직일 때 실행 이미지로 사용할 앱 번들 내 이미지 파일의 이름입니다

Braze 메시지 작성기는 alert 및 해당 속성, content-available, sound, category 키를 자동으로 생성합니다.

이 값은 푸시 메시지를 작성할 때 설정 탭에서 입력할 수 있습니다. 알림 옵션을 선택하고 알림 사전 키를 선택하면 새 키-값 항목에 해당 키가 자동으로 채워집니다.

푸시 메시지 작성 시 설정 탭의 알림 옵션에서 알림 사전 키를 선택하면 새 키-값 항목에 키가 자동으로 채워지는 화면.

Braze가 APNs로 푸시 알림을 보낼 때 페이로드는 JSON 형식으로 지정됩니다.

단순 페이로드




{
    "aps" : { "alert" : "Message received from Spencer" },
}

복합 페이로드




{
    "aps" : {
        "alert" : {
            "body" : "Hi, welcome to our app!",
            "loc-key" : "France",
            "loc-args" : ["Bonjour", "bienvenue"],
            "action-loc-key" : "Button_Type_1",
            "launch-image" : "Paris"
      },
        "content-available" : 1
    },
}
커스텀 키-값 페어

aps 라이브러리 페이로드 값 외에도 사용자 기기로 커스텀 키-값 페어를 보낼 수 있습니다. 이러한 페어의 값은 사전(오브젝트), 배열, 문자열, 숫자, 부울 같은 기본 유형으로 제한됩니다.

커스텀 키-값 페어를 입력하는 화면.

커스텀 키-값 페어는 내부 측정기준 관리, 사용자 인터페이스의 컨텍스트 설정 등에 사용할 수 있으며 이에 국한되지 않습니다. Braze를 사용하면 푸시 알림과 함께 추가 키-값 페어를 전송하여 애플리케이션에서 extras 키를 통해 사용할 수 있습니다. 다른 키를 사용하려면 앱이 해당 커스텀 키를 처리할 수 있는지 확인하세요.

Apple은 고객 정보나 민감한 데이터를 커스텀 페이로드 데이터에 포함하지 않도록 권고합니다. 또한 알림 메시지와 연결된 작업이 기기의 데이터를 삭제하지 않도록 할 것을 권장합니다.

API 트리거 Campaigns

Braze를 사용하면 extras라고 하는 사용자 정의 문자열 키-값 페어를 보낼 수 있습니다. API 트리거 Campaign 및 예약된 API 트리거 Campaign에서 extras에 액세스하려면 대시보드에서 키를 “example_key”로, 값을 "$json:{"foo": 1, "bar": 1}"로 설정합니다. 그러면 개발자 콘솔에 "extras": { "test": { "foo": 1, "bar": 1 }가 출력됩니다.

Android

Braze를 사용하면 키-값 페어를 사용해 푸시 알림에 추가 데이터 페이로드를 보낼 수 있습니다.

데이터 페이로드

iOS 푸시와 마찬가지로 사용자 기기로 커스텀 키-값 페어를 보낼 수 있습니다.

커스텀 키-값 페어는 내부 측정기준 관리, 사용자 인터페이스의 컨텍스트 설정 등에 사용할 수 있으며, 원하는 어떤 용도로든 활용할 수 있습니다.

API 트리거 Campaigns

Braze를 사용하면 extras라고 하는 사용자 정의 문자열 키-값 페어를 보낼 수 있습니다. API 트리거 Campaign 및 예약된 API 트리거 Campaign에서 extras에 액세스하려면 대시보드에서 키를 “example_key”로, 값을 "$json:{"foo": 1, "bar": 1}"로 설정합니다. 그러면 개발자 콘솔에 "extras": { "test": { "foo": 1, "bar": 1 }가 출력됩니다.

FCM 메시징 옵션

Android 푸시 알림은 FCM 메시지 옵션으로 더 세부적으로 커스텀할 수 있습니다. 여기에는 알림 우선순위, 사운드, 지연, 수명, 축소 가능 여부가 포함됩니다. 이 값은 푸시 메시지를 만들 때 설정 탭에서 지정할 수 있습니다. Braze 메시지 작성기에서 이러한 옵션을 설정하는 방법에 대한 자세한 내용은 고급 푸시 알림 설정을 참조하세요.

FCM 메시징 옵션을 설정하는 화면.

무음 푸시 알림

무음 푸시 알림은 알림 메시지나 사운드가 없는 푸시 알림으로, 백그라운드에서 앱의 인터페이스나 콘텐츠를 업데이트하는 데 사용됩니다. 이러한 알림은 키-값 페어를 사용하여 백그라운드 앱 작업을 트리거합니다. 무음 푸시 알림은 제거 추적 기능에도 사용됩니다.

마케터는 앱 사용자에게 무음 푸시 알림을 보내기 전에 예상대로 동작하는지 테스트해야 합니다. iOS 또는 Android 무음 푸시 알림을 작성한 후, 외부 사용자 ID 또는 이메일 주소로 필터링하여 테스트 사용자만 타겟팅하도록 하세요.

Campaign을 시작한 후에는 테스트 기기에 눈에 보이는 푸시 알림이 수신되지 않았는지 확인해야 합니다.

인앱 메시지

메시지 작성기에서 만드는 모든 인앱 메시지에 키-값 페어를 추가할 수 있습니다.

  1. Campaign 또는 Canvas에서 인앱 메시지를 만들거나 편집합니다.
  2. 메시지 작성기에서 설정 탭을 선택합니다.
  3. 키-값 페어에서 새 페어 추가를 선택합니다.
  4. 각 페어의 키와 값을 입력합니다. 페어를 더 추가하려면 새 페어 추가를 다시 선택합니다.

API 트리거 Campaign

Braze에서는 extras라고 하는 커스텀 정의 문자열 키-값 페어를 보낼 수 있습니다. API 트리거 Campaign 및 예약된 API 트리거 Campaign에서 extras에 액세스하려면 대시보드에서 키를 “example_key”로, 값을 "$json:{"foo": 1, "bar": 1}"로 설정합니다. 그러면 개발자 콘솔에 "extras": { "test": { "foo": 1, "bar": 1 }이 출력됩니다.

이메일

SparkPost와 SendGrid 모두 이메일에서 키-값 페어를 지원합니다. SendGrid를 사용하는 경우 키-값 페어는 고유 인수로 전송됩니다. SendGrid에서는 최대 10,000바이트의 데이터 범위 내에서 키-값 페어를 개수 제한 없이 첨부할 수 있습니다. 이러한 키-값 페어는 SendGrid 이벤트 웹훅의 게시물에서 확인할 수 있습니다.

Braze 이메일 메시지 작성기의 발송 정보 탭.

Content Cards

Content Cards에 키-값 페어를 추가하려면 Braze 메시지 작성기의 설정 탭으로 이동하여 새 페어 추가를 선택합니다.

Content Cards에 키-값 페어 추가

Braze 고객 참여 플랫폼 문서.

리소스
법적 고지
회사
© 2026 Braze, Inc. All rights reserved.
브레이즈 상태 확인
New Stuff!