데이터 전송 프로세스

Braze에서의 데이터 전송 프로세스는 Native 영역은 일반적인 태깅을 통한 SDK 전송이 진행됩니다.

Hybrid 영역은 앱/웹 분기처리 및 인터페이스를 통해 Webview 데이터를 Native 영역으로 전달하여 전송합니다.

Hybrid 영역에서 별도 분기처리가 되지 않을 경우, Braze 솔루션 활용 간 기능 제한 및 이슈가 발생될 수 있습니다.

SDK 설치

SDK는 npm, yarn, CDN 방식으로 설치할 수 있습니다.

대시보드에서 API Key 확인

Braze 대시보드 Manage Settings → WEB 앱 등록 후 API Key와 SDK Endpoint를 확인합니다.

SDK 최신 설치 링크: braze-web-sdk — loading-snippet.js

CDN 연동 방식

• CDN 스니펫을 통해 Braze SDK를 로드합니다.
• 연동 시 API_KEY와 baseUrl(SDK Endpoint)를 설정합니다. (Braze 대시보드에서 발급)
• 대시보드: Manage Settings → + Add App에서 WEB 앱을 등록합니다.

CDN 스니펫은 공식 저장소의 loading-snippet.js 전문을 사용하세요. 아래는 구조 참고용으로, 실제 연동 시 최신 스니펫 URL·버전을 반영해 주세요.

<script type="text/javascript">
  // loading-snippet.js 전문 (공식 GitHub 참고)
  // … Braze SDK 로더 …
  y.src = 'https://js.appboycdn.com/web-sdk/5.9/braze.min.js';
</script>

초기화

braze.initialize(apiKey, options)로 SDK를 활성화한 뒤, 인앱 메시지 자동 표시·세션 시작 순서로 호출합니다.

braze.initialize('YOUR-API-KEY-HERE', {
  baseUrl: 'YOUR-SDK-ENDPOINT-HERE'
});

// 인앱 메시지 자동 표시 (Soft Prompt 사용 시 제거 — 참고 사항)
braze.automaticallyShowInAppMessages();

// Braze 세션 시작 (데이터 포인트 수집)
braze.openSession();

baseUrl은 대시보드에 표시된 SDK Endpoint 값입니다. API Key와 Endpoint는 앱(WEB) 단위로 발급됩니다.

External ID

Braze에 연동하면 SDK 초기화 시 anonymous device ID가 생성됩니다. 로그인 시점에는 고객사 고유 식별자를 External ID로 설정합니다.

중요: 로그인 식별자는 고객사 보안 정책에 맞게 설정하며, 국내 보안 정책상 일방향 암호화 적재를 권장합니다.

braze.changeUser('고객사 고유 식별자');

Event

• Braze SDK를 통해 Custom Event를 전송합니다.
• 이벤트명만 전송하거나, 이벤트 속성(Object)을 함께 전달할 수 있습니다.
• 이벤트명·속성명은 텍소노미 기획 문서와 동일하게 유지하세요.

이벤트명만 전송

braze.logCustomEvent('이벤트명');

이벤트 속성 포함

braze.logCustomEvent('이벤트명', {
  '이벤트 속성명': '값',                        // String
  '이벤트 속성명': false,                       // Boolean
  '이벤트 속성명': 42,                          // Number
  '이벤트 속성명': new Date(),                  // Date
  '이벤트 속성명': ['any', 'array', 'here'],    // Array
  '이벤트 속성명': { deeply: ['nested', 'json'] } // Object
});

즉시 전송 (Flush)

Braze SDK는 배치성으로 전송되기 때문에 민감성 데이터는 requestImmediateDataFlush()를 호출해 실시간으로 전송되도록 구성합니다.

braze.requestImmediateDataFlush();

Standard Attribute

Braze가 미리 정의한 사용자 속성입니다. 이름, 성별, 전화번호, 생년월일 등 braze.getUser() 메서드로 설정합니다.

Attribute는 Standard Attribute와 Custom Attribute로 구분됩니다.

이름 설정

braze.getUser().setFirstName('이름');

성별 설정

braze.getUser().setGender(braze.User.Genders.FEMALE);

전화번호 설정

braze.getUser().setPhoneNumber('+821012345678');

전화번호는 국가번호 형식(예: +821012345678)으로 업로드해야 합니다. 010 등 로컬 형식은 사용하지 마세요.

생년월일 설정

braze.getUser().setDateOfBirth(2000, 12, 25);

즉시 전송 (Flush)

Braze SDK는 배치성으로 전송되기 때문에 민감성 데이터는 requestImmediateDataFlush()를 호출해 실시간으로 전송되도록 구성합니다.

braze.requestImmediateDataFlush();

Custom Attribute

고객사가 정의하는 사용자 속성입니다. String, Number, Boolean, Date, Array 등 타입별로 설정 방법이 다릅니다.

String · Number · Boolean 등

braze.getUser().setCustomUserAttribute(
  '속성 키',
  '속성 값'
);

Date (ISO-8601)

Date 형태 속성에 년·월·일만 전달하면 문자열로 인식될 수 있습니다. Braze에는 ISO-8601 형식(예: 2013-07-16T19:20:30+09:00)으로 업데이트하세요.

braze.getUser().setCustomUserAttribute(
  '속성 키',
  '2013-07-16T19:20:30+09:00'
);

Array

고객 이력 정보(예: 검색·구매 이력)를 활용한 개인화 코드 목적으로 사용됩니다. 이러한 이력 정보가 DB에 없는 값이라면 Add/Remove 함수만 사용하여 이력 정보를 최신화하도록 구성합니다.

// 전체 배열 설정
braze.getUser().setCustomUserAttribute('속성 키', ['값1', '값2']);

// 배열에 추가
braze.getUser().addToCustomAttributeArray('속성 키', '추가 값');

// 배열에서 제거
braze.getUser().removeFromCustomAttributeArray('속성 키', '제거 값');

속성 삭제 (null)

braze.getUser().setCustomUserAttribute('속성 키', null);

즉시 전송 (Flush)

Braze SDK는 배치성으로 전송되기 때문에 민감성 데이터는 requestImmediateDataFlush()를 호출해 실시간으로 전송되도록 구성합니다.

braze.requestImmediateDataFlush();

Purchase

Purchase event (Legacy)

• 구매 이벤트는 logPurchase로 전송합니다.
• 상품 ID, 가격, 통화, 수량을 지정할 수 있으며, 추가 속성은 Purchase Property로 전달합니다.

기본 구매

braze.logPurchase('product_id', price, 'USD', quantity);
// productId: String
// currency: 기본 USD (KRW는 별도 Braze 설정 확인)
// price: Number
// quantity: Number

구매 속성 포함

var purchaseProperties = {};
purchaseProperties['속성명'] = '값';
braze.logPurchase('product_id', price, 'USD', quantity, purchaseProperties);

eCommerce Recommended Event

Braze의 eCommerce Recommended Event는 정해진 이벤트명과 스키마(속성 구조)를 가진 커스텀 이벤트입니다. 이벤트가 스키마 검증을 통과하면 Braze가 매출 계산, 장바구니 상태 관리 등 후처리를 자동으로 수행합니다.

이벤트명·속성명은 텍소노미 기획 문서와 동일하게 유지하세요. 아래 예시의 Braze 권장 이벤트명·스키마 필드는 참고용이며, metadata 등 커스텀 속성 키/값은 기획 문서 명세를 따릅니다.

핵심 개념

이벤트명은 정확히(case-sensitive) 아래 canonical name을 사용해야 합니다. 이름이 다르면 일반 Custom Event로 처리되어 eCommerce 후처리가 동작하지 않습니다. 속성명도 텍소노미 기획 문서에 정의된 키를 그대로 사용하세요.

• ecommerce.product_viewed
• ecommerce.cart_updated
• ecommerce.checkout_started
• ecommerce.order_placed
• ecommerce.order_cancelled
• ecommerce.order_refunded

위 다이어그램은 Braze eCommerce recommended events에서 정의한 구매 여정 6단계(조회 → 장바구니 → 체크아웃 → 주문완료 → 취소 → 환불)를 요약한 이미지입니다.

주문 완료(결제 완료) — ecommerce.order_placed (권장)

주문/결제 성공 시점에 ecommerce.order_placed를 전송합니다. 이 이벤트는 Braze에서 주요 매출 드라이버로 처리되며, 검증이 통과하면 사용자 프로필의 Total Revenue(total_value 기준) 및 Total Orders가 자동 업데이트됩니다.

예시 (Web SDK — logCustomEvent)

braze.logCustomEvent('ecommerce.order_placed', {
  order_id: 'ord_77821',
  cart_id: 'cart_abc123', // 선택
  total_value: 224.96,
  subtotal_value: 209.97, // 선택
  tax: 9.0,               // 선택
  shipping: 5.99,         // 선택
  currency: 'USD',
  products: [
    {
      product_id: 'SKU-RUN-4821',
      product_name: 'Ultraboost Running Shoe',
      variant_id: 'UB-BLK-11',
      quantity: 1,
      price: 189.99,
      metadata: {
        color: 'Core Black',
        size: '11'
      }
    }
  ],
  source: 'web',
  metadata: {
    order_status_url: 'https://www.example.com/orders/ord_77821/status',
    gift_wrapped: true
  }
});

장바구니 업데이트 — ecommerce.cart_updated

장바구니 변경 시점마다 전송합니다. action을 사용해 증분(add/remove) 방식 또는 전체 교체(replace 또는 action 생략) 방식 중 하나를 선택합니다.

동일 cart_id에 대해 증분 방식과 전체 교체 방식을 섞어 쓰는 것은 권장되지 않습니다.

예시 (add — 증분 추가)

braze.logCustomEvent('ecommerce.cart_updated', {
  cart_id: 'cart_abc123',
  action: 'add',
  currency: 'USD',
  source: 'web',
  products: [
    {
      product_id: 'SKU-RUN-4821',
      product_name: 'Ultraboost Running Shoe',
      variant_id: 'UB-BLK-11',
      quantity: 1,
      price: 189.99
    }
  ]
});

예시 (replace — 전체 장바구니 교체, total_value 필수)

braze.logCustomEvent('ecommerce.cart_updated', {
  cart_id: 'cart_abc123',
  action: 'replace',
  total_value: 234.96,
  currency: 'USD',
  source: 'web',
  products: [
    {
      product_id: 'SKU-RUN-4821',
      product_name: 'Ultraboost Running Shoe',
      variant_id: 'UB-BLK-11',
      quantity: 1,
      price: 189.99
    }
  ]
});

체크아웃 시작 — ecommerce.checkout_started

체크아웃 진입 시점(체크아웃 버튼 클릭 또는 체크아웃 페이지 진입 등)에 전송합니다.

주문 취소/환불 — ecommerce.order_cancelled, ecommerce.order_refunded

• ecommerce.order_cancelled: Total Orders를 감소시키며, 매출(total revenue)에는 영향을 주지 않습니다.
• ecommerce.order_refunded: refund 금액만큼 Total Revenue를 감소시키고 Total Refund Value를 증가시킵니다. 부분 환불은 total_value에 환불 금액만 전달합니다.

구현/운영 시 참고

• ecommerce.order_cancelled · ecommerce.order_refunded는 typed SDK class/API가 없어 logCustomEvent()로 스키마에 맞게 전송합니다.
• 통화(currency)는 ISO 4217 3자리 코드를 사용하며, Non-USD 통화는 자동으로 USD로 환산되어 매출 지표에 반영됩니다.
• 이벤트 검증 실패 시, 권장 이벤트는 사용자 프로필에 적재되지 않고 드롭될 수 있습니다. (REST API는 응답의 errors 배열로 확인 가능)
• 레거시 Purchase event와 권장 이벤트를 같은 주문에 대해 동시에 내면 매출이 중복 집계될 수 있으니 전환 시 유의하세요.

Push

WEB 푸시는 사이트 루트에 service-worker.js를 두고, Braze Service Worker 스크립트를 import 합니다.

service-worker.js (Website root)

self.importScripts('https://js.appboycdn.com/web-sdk/5.7/service-worker.js');

self.importScripts를 사용하는 경우 Service Worker 파일은 반드시 사이트 루트에 위치해야 합니다.

푸시 권한 요청

braze.requestPushPermission();

In-App Message

Braze 인앱 메시지는 Modal, Slide, Full, Custom HTML, Simple Survey 등 유형이 있으며, 기본 z-index는 10600입니다.

Custom HTML 설정을 제외한 아래 초기화 옵션(z-index, 명시적 닫기 등)은 필수가 아닌 옵션입니다. 서비스 UI에 맞게 선택 적용하세요.

z-index 조정

braze.initialize('YOUR-API-KEY', {
  baseUrl: 'YOUR-API-ENDPOINT',
  inAppMessageZIndex: 12000
});

명시적 닫기 필요

braze.initialize('YOUR-API-KEY', {
  baseUrl: 'YOUR-API-ENDPOINT',
  requireExplicitInAppMessageDismissal: true
});

Custom HTML (사용자 JavaScript 허용)

braze.initialize('YOUR-API-KEY', {
  baseUrl: 'YOUR-API-ENDPOINT',
  allowUserSuppliedJavascript: true
});

하이브리드

WebView에서는 네이티브 브릿지로 Custom Event·Custom Attribute를 전달합니다. User-Agent에 BrazeAndroid / BrazeiOS 문자열이 포함된 경우 네이티브 SDK로 위임합니다.

아래 코드는 고객사 이해를 돕기 위한 예시입니다. 자체적으로 사용 중인 인터페이스 코드를 활용해 운영하셔도 됩니다.

WebView — Custom Event (예시)

function sendEventToNative(eventName, interfaceData) {
  try {
    interfaceData['EventName'] = eventName;
    var userAgent = navigator.userAgent;
    if (userAgent.indexOf('BrazeAndroid') > -1) {
      NativeBridge.trackingEvent(interfaceData);
    } else if (userAgent.indexOf('BrazeiOS') > -1) {
      webkit.messageHandlers.NativeCallback.postMessage(interfaceData);
    }
  } catch (e) {
    console.log('Hybrid Error : ' + e);
  }
}

하이브리드 연동 시 WebView에서 WEB SDK로 직접 이벤트를 보내지 않고, 위와 같이 네이티브 브릿지로 APP 채널에 전달합니다.

WebView — Custom Attribute (예시)

function sendAttrToNative(customObject) {
  try {
    var userAgent = navigator.userAgent;
    if (userAgent.indexOf('BrazeAndroid') > -1) {
      NativeBridge.trackingAttr(customObject);
    } else if (userAgent.indexOf('BrazeiOS') > -1) {
      customObject['EventName'] = 'customAttribute';
      webkit.messageHandlers.NativeCallback.postMessage(customObject);
    }
  } catch (e) {
    console.log('Hybrid Error : ' + e);
  }
}

var dataObject = {
  memberage: '19',
  membergender: 'F',
  membership: 'FRIENDS'
};
sendAttrToNative(dataObject);

최종 반영 예시 코드

연동 완료 시 <head> 또는 공통 스크립트에 반영하는 예시 패턴입니다.

PC · Mobile WEB

<script type="text/javascript">
  // loading-snippet.js 로드 후
  braze.initialize('YOUR-API-KEY', {
    baseUrl: 'YOUR-SDK-ENDPOINT',
    allowUserSuppliedJavascript: true
  });
  braze.automaticallyShowInAppMessages();
  if (로그인 여부) {
    braze.changeUser('고객사 고유 식별자');
  }
  braze.requestPushPermission();
  braze.openSession();
</script>

WebView (하이브리드)

if (WEB 환경) {
  // 위 WEB 초기화
} else if (App WebView) {
  sendEventToNative('Braze APP 이벤트', eventProperty);
  sendAttrToNative(dataObject);
}

중요: 이벤트명·속성명·Attribute 키/값은 텍소노미 기획 문서 명세로 교체해 주세요.

태깅 예시

실제 서비스 태깅 시 참고할 수 있는 호출 순서 예시입니다.

로그인 완료 — Custom Event

if (로그인 여부) {
  braze.changeUser('고객사 고유 식별자');
}
braze.logCustomEvent('로그인 완료', {
  event_name: '로그인 완료',
  event_time: '2024-07-04T13:00:00',
  loginyn: true,
  platform: 'Mobile WEB'
});
braze.requestImmediateDataFlush();

검색 — Custom Event & Custom Attribute

if (로그인 여부) {
  braze.changeUser('고객사 고유 식별자');
}
braze.getUser().addToCustomAttributeArray(
  'searchkeyword_url',
  'id_1710805494/url_REV$lang=EN$site=KO$tripType=~'
);
braze.getUser().addToCustomAttributeArray(
  'searchkeyword',
  'id_1710805494/biztype_REV/항공권_국제 ~'
);
braze.logCustomEvent('검색', {
  event_name: '검색',
  event_time: '2024-07-04T13:00:00',
  loginyn: true,
  platform: 'Mobile WEB',
  biztype: 'REV',
  airtype: '국제',
  arrive: 'YVR',
  search_url: 'id_1710805494/url_REV$l ~',
  jourenytype: '왕복',
  startlocation: 'ICN',
  startdate: '2024-12-11T15:00:00',
  enddate: '2024-12-21T11:00:00'
});
braze.requestImmediateDataFlush();

Soft Prompt

사용자 경험을 위해 브라우저 기본 푸시 팝업 대신 인앱 메시지로 권한을 요청할 수 있습니다. Soft Prompt를 사용할 때는 automaticallyShowInAppMessages() 호출을 제거하거나, subscribeToInAppMessage에서 직접 표시 여부를 제어합니다.

braze.subscribeToInAppMessage(function (inAppMessage) {
  if (inAppMessage instanceof braze.InAppMessage) {
    const keyValuePairs = inAppMessage.extras || {};
    if (keyValuePairs['softprompt'] === 'true') {
      if (
        braze.isPushSupported() === false ||
        braze.isPushPermissionGranted() ||
        braze.isPushBlocked()
      ) {
        return;
      }
      if (inAppMessage.buttons[0]) {
        inAppMessage.buttons[0].subscribeToClickedEvent(function () {
          braze.requestPushPermission(
            function () { /* 허용 */ },
            function () { /* 거부 */ }
          );
        });
      }
    }
  }
  braze.showInAppMessage(inAppMessage);
});

인앱 메시지 캠페인의 extras에 softprompt: true를 설정해 Soft Prompt용 메시지를 구분합니다.

연동 체크리스트

• 대시보드 WEB 앱 등록 · API Key · SDK Endpoint 확인
• CDN 스니펫(최신 버전) · braze.initialize · openSession
• 로그인 시 changeUser(External ID) 호출
• Custom Event / Standard·Custom Attribute / eCommerce Recommended Event 텍소노미 반영
• 루트 service-worker.js · requestPushPermission (또는 Soft Prompt)
• 하이브리드 WebView — WEB SDK 이중 초기화 없이 네이티브 브릿지(인터페이스 코드) 사용
• 대시보드 User Search · Custom Event 수신 확인