Braze 입문 3편 — Developer Guide · Identity · 데이터 모델 깊이

이 글은 Braze 입문에서 운영까지 시리즈 3편이에요. 1편 의 큰 그림 · 2편 의 5분 통합 다음 — Developer Guide 자체의 구조 + Identity · 데이터 모델의 깊이.

이번 글의 위치

2편이 코드 박는 5분 이었다면, 3편은 그 코드가 진짜 운영에 들어가기 전 짚어둘 자리. 특히 Identity 설계 — External ID 한 줄 결정 이 6개월 후 모든 분석의 기반. 처음에 잘못 박으면 나중에 마이그레이션 비용 폭증.

Developer Guide 4 큰 섹션 — 어디서 무엇을 찾나

Developers can find everything they need to know about the Braze SDK 가 Developer Guide 의 목적. — 공식 docs

SDK (Software Development Kit, 앱에 박는 통합 라이브러리) 통합 문서는 네 큰 자리로 나뉘어요.

→ 처음 시작 = 1 → 2 → 3 → 4 순서. 각 섹션이 역할별로 가는 자리 가 달라요.

권장 학습 경로 5 단계

1. SDK Overview — 플랫폼 아키텍처 이해
   ↓
2. Integration Overview — 시스템 전체상 파악
   ↓
3. Featured Integration 선택 — Web · Android · Swift 중 우리 stack
   ↓
4. Initial SDK Setup — 5분 통합 (2편)
   ↓
5. 필요 기능 모듈 — Push · In-app · Content Card · Feature Flag

2편 이 4 단계 까지였다면, 3편은 1·2 단계를 다시 + 5 단계의 깊이 안내.

SDK 의 데이터 흐름

Braze SDK 가 내부적으로 무엇을 하는지 의 그림:

[사용자 앱/웹]
   ↓ (SDK API 호출)
   logCustomEvent · setCustomAttribute · logPurchase · changeUser
   ↓
[SDK 내부 buffer]
   - 메모리 + 로컬 저장
   - background queue
   ↓ (주기적 sync · 또는 force flush)
[Braze Server]
   - 사용자 프로필 update
   - 이벤트 저장
   - segment 평가
   - 캠페인·Canvas trigger 검사
   ↓ (메시지 발송 결정 시)
[사용자 앱/웹]
   - push 수신
   - in-app message 표시
   - content card 추가

여기서 짚어둘 함정 — SDK 호출이 즉시 server 전송 아님. Buffer + background sync 구조라, 마지막 호출 후 사용자가 앱 종료 시 일부 데이터 손실 가능. flushData() 같은 명시 호출 또는 Server-side REST API 안전망이 그래서 필요해요 (2편 패턴 5).

Identity Management — Braze 운영의 처음이자 끝

여기가 Developer Guide 의 가장 중요한 자리. 2편 External ID 설계 의 깊이 풀이.

External ID 의 의미

External ID 없이는 Braze 가 anonymous ID 할당 → API 기능 제한. — 공식 docs

External ID (외부 시스템 사용자 식별자) = 우리 시스템과 Braze 의 연결 키. 이게 없으면 API 호출이 anonymous user (익명 사용자) lookup 으로 제한되고, 모바일과 웹의 같은 사용자가 분리 인식돼 cross-device tracking 도 끊겨요. 거기에 segment 정확도가 떨어지고 나중에 마이그레이션도 까다로워집니다.

→ 로그인 즉시 External ID 박기 가 운영의 기본.

changeUser() 의 4 동작 — 시험 함정 자리

changeUser(externalId) 호출 시 4 시나리오 별 동작 이 다름:

정말 중요한 자리 — Anonymous → 기존 ID 는 merge 안 됨. 이미 존재하는 user 에 anonymous 활동 을 붙이려는 시도가 기본 동작 으로는 안 됨. 별도 Identity Merge API 또는 User Alias (사용자 별칭, 부가 식별자) 활용.

Anonymous → 새 ID merge — 표준 흐름

// 1. 사용자 가입 전 — anonymous 상태
// Braze 가 자동 anonymous ID 부여 (changeUser 호출 X)

// 2. anonymous 행동 추적
braze.logCustomEvent("landing_viewed", { ... });
braze.logCustomEvent("product_viewed", { ... });

// 3. 가입 완료 시점
const newUserId = await api.signup({ ... });

// 4. ★ changeUser 호출 — anonymous 프로필이 newUserId 로 merge
braze.changeUser(newUserId);
// → 이전 landing_viewed · product_viewed 가 newUserId 에 속함

핵심 — anonymous → 새 ID merge 가 자연스럽게 작동 하는 가장 흔한 패턴. 가입 funnel 의 모든 이전 행동 보존.

Anonymous → 기존 ID 의 함정

// 시나리오: 이미 가입한 사용자가 로그아웃 후 다시 로그인
// 1. 로그아웃 시 — 일부 사람이 잘못 박음
braze.changeUser("anonymous-temp");  // ✗ 잘못

// 2. 다시 anonymous 상태로 행동
braze.logCustomEvent("...", { ... });

// 3. 다시 로그인
braze.changeUser(existingUserId);
// → 단계 2의 행동이 existingUserId 에 merge 안 됨 (사라짐)

→ 절대 금지: 로그아웃 시 changeUser 호출. 기본 동작이 anonymous merge 를 지원 안 함.

Best Practice — External ID 선택

UUID 형식 (128-bit random) 또는 기존 ID 해시 사용. — 공식 docs

좋은 후보:

나쁜 후보 — 보안 취약 :

Sequential integer (1, 2, 3 처럼 순차 정수) 는 추측이 너무 쉬워서 다른 사용자 profile 노출로 이어질 수 있고, Email 이나 Phone 은 사용자가 언제든 바꿀 수 있고, Session ID 는 접속할 때마다 다른 값이라 안정 식별자로 못 써요.

여기서 짚어둘 자리 하나 — 추측 가능 ID 의 보안 위험. 만약 External ID 가 sequential 1, 2, 3, ... 인데 API key 가 노출되면, 공격자가 모든 사용자 profile 조회 가능. UUID 또는 hash 가 security by obscurity 가 아니라 enumeration 공격 회피 (순차 추측으로 전체 데이터 긁기 차단).

User Alias — anonymous 의 부가 식별

// Anonymous 사용자에게 alias 부여 (External ID 없이)
braze.getUser().addAlias("device-fingerprint-xyz", "anonymous_device");

// 또는 legacy 시스템 ID
braze.getUser().addAlias("legacy-12345", "legacy_system");

Alias 의 두 구성 — name (값) + label (네임스페이스).

대표 사용 자리는 anonymous 상태에서 API 로 targeting 할 때, legacy 시스템 ID 마이그레이션 할 때, CRM (Customer Relationship Management, 고객 관계 관리) contact ID 매핑할 때, 외부 마케팅 도구 식별자 연결할 때 정도.

절대 금지 패턴 2종

금지 1: Shared default ID

// ✗ 절대 금지
braze.changeUser("default-user");

왜 위험 — 공유 디바이스 (가족 공용 태블릿 · 매장 키오스크) 에서 여러 사람 활동 이 한 ID 로 통합 → re-engagement (재참여 캠페인) 시 엉뚱한 사람에게 메시지.

금지 2: Logout 시 changeUser

// ✗ 절대 금지
function onLogout() {
    braze.changeUser(null);    // 또는 다른 default ID
}

왜 위험 — 같은 디바이스의 다음 anonymous 활동 이 이전 사용자 profile 에 잘못 누적. 또는 anonymous 활동 손실.

올바른 logout — 별도 처리 없음. SDK 가 알아서 처리. 다음 changeUser 호출 시 자연스럽게 전환.

데이터 모델 4 단위 — 깊이 풀이

2편 에서 본 4 단위의 각 모델 별 깊이.

1. Custom Attributes — 사용자 상태

// Set (덮어쓰기)
braze.getUser().setCustomAttribute("tier", "premium");
braze.getUser().setCustomAttribute("signup_year", 2025);
braze.getUser().setCustomAttribute("is_verified", true);

// Increment (누적 카운터)
braze.getUser().incrementCustomUserAttribute("total_logins", 1);
braze.getUser().incrementCustomUserAttribute("total_spent", 50000);

// Array — push/remove
braze.getUser().addToCustomAttributeArray("favorite_categories", "shoes");
braze.getUser().removeFromCustomAttributeArray("favorite_categories", "books");

// Set Array (전체 교체)
braze.getUser().setCustomAttribute("tags", ["vip", "early_adopter"]);

Attribute 의 4 type — String 은 text 값, Number 는 integer 와 float, Boolean 은 true/false, Array 는 동질 요소 list.

Attribute 의 핵심 함정 — Cardinality

Cardinality (한 필드가 가질 수 있는 서로 다른 값의 개수) 가 통제돼야 하는 자리.

✓ tier: "free" / "premium" / "enterprise"    (3 값)
✓ country: "KR" / "JP" / "US" / ...           (~200 값)
✓ language: "ko" / "en" / "ja"                (~10 값)

✗ signup_timestamp: 매 사용자 unique          (cardinality = users 수)
✗ session_id: 매번 다름                       (cardinality 무한)
✗ ip_address: 사용자별 다름                    (high cardinality)

5편 Statsig cardinality 와 동일 원칙. 분류 가능한 카테고리만 attribute. 고유 값은 event property 또는 별도 시스템.

Attribute 의 set 시점 — 일관성

// 좋은 패턴 — 사용자 factory 함수
function syncUserToBraze(user: User) {
    braze.changeUser(user.id);
    braze.getUser().setEmail(user.email);
    braze.getUser().setCountry(user.country);
    braze.getUser().setLanguage(user.language);
    braze.getUser().setCustomAttribute("tier", user.tier);
    braze.getUser().setCustomAttribute("signup_year", user.signupYear);
    // ... 모든 핵심 attribute 동시 sync
}

시점 — 로그인 시 full sync, 사용자 정보 변경 시 (예: tier 업그레이드), 첫 결제 후 LTV (Lifetime Value, 고객 생애 가치) 관련 자리. 매 화면 전환마다 set 은 X — 불필요 sync.

2. Custom Events — 사용자 행동

braze.logCustomEvent("product_viewed", {
    product_id: "P-123",
    category: "shoes",
    price: 50000,
    in_stock: true
});

braze.logCustomEvent("search_performed", {
    query: "summer dress",
    results_count: 47
});

Event 의 특성 — timestamp 자동 부여 (서버 측 또는 SDK 시각), append-only (한번 박힌 event 는 수정 안 됨), 같은 event 가 여러 번 박혀도 모두 누적 보존, properties 는 JSON object (string · number · boolean · array).

Event 의 Naming Convention

✓ 동사_명사 + snake_case
  product_viewed
  cart_added
  checkout_started
  signup_completed
  notification_dismissed

✗ 일관성 없음
  ProductViewed (camelCase 혼용)
  view (너무 일반)
  product_view (시제 모호)

5편 Statsig event 설계 의 원칙 그대로.

Property cardinality

✓ category: "shoes" / "books" / "electronics"  (분류 가능)
✓ payment_method: "card" / "kakao_pay" / ...    (5~10 값)

✗ product_id: 수만 종                            (high cardinality)
✗ user_id: 사용자별 unique                      (Event 의 user 는 이미 외부)

한도

대부분 SDK = event 당 properties 수 한도 + property 값 크기 한도. 보통 event 당 properties 64개 + 값 255자 정도. 큰 콘텐츠는 URL · ID 만 박고 외부 lookup.

3. Purchases — 결제 별도 모델

braze.logPurchase(
    "product_id",
    50000,
    "KRW",
    1,
    {
        category: "shoes",
        discount_applied: true,
        campaign_source: "email-2026-summer"
    }
);

왜 별도 모델인가 — Purchase 가 LTV · ARPU (Average Revenue Per User, 사용자당 평균 매출) · 결제 기반 segment 의 표준 자리.

Custom Event "purchase" 로 박으면:
  - LTV 자동 계산 X
  - "Top 10% 결제 사용자" segment 자동 X
  - revenue dashboard 자동 X

Purchase 별도 모델:
  - LTV · ARPU · cohort revenue 자동
  - 결제 기반 segment 풍부
  - 환불 처리 가능

Purchase 의 시점

// 결제 완료 직후
async function onCheckoutCompleted(order) {
    for (const item of order.items) {
        braze.logPurchase(
            item.productId,
            item.price,
            order.currency,
            item.quantity,
            {
                category: item.category,
                order_id: order.id,
                payment_method: order.paymentMethod
            }
        );
    }

    // Server side 동시 (안전망)
    await api.post("/braze/sync-purchase", { orderId: order.id });
}

Server side 동시 추적 권장 — Client 가 앱 종료 · 네트워크 끊김 으로 Braze sync 실패 가능. Server REST API 가 결제 정확성 보장.

4. Sessions — 자동 추적

SDK 가 session 자동 관리. — 일반 SDK 통합 패턴

Session 정의 — 사용자가 앱 active 상태 시작에서 종료까지. 기본 비활성 30초 후 자동 session 종료 (SDK 설정 가능). Web 은 page 진입에서 30분 무활동 시 종료.

SDK 가 자동 박는 데이터:

• session_started event
• session_ended event
• session duration
• 마지막 active 시각

→ 코드 없이도 자동. 분석 dashboard 에서 session 통계 자동.

Session 의 활용

Segment "최근 active 사용자":
  - Last Used App: within 7 days
  - Sessions in last 30 days: > 3

세션 기반 segment 가 retention 분석·re-engagement 캠페인 의 표준.

SDK 의 background sync · push token · 권한

Background Sync

SDK 호출 → buffer
   ↓
주기적 sync (예: 30초마다 또는 background)
   ↓
Braze Server

기본 자동. flushData() 호출로 즉시 sync 강제 가능 (앱 종료 직전 권장).

Push Token 등록

iOS — APNs (Apple Push Notification service) token 등록:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    AppDelegate.braze?.notifications.register(deviceToken: deviceToken)
}

Android — FCM (Firebase Cloud Messaging) token:

class MyFirebaseMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Braze.getInstance(applicationContext).registeredPushToken = token
    }
}

Web — Service Worker + Web Push API:

braze.requestPushPermission((isPushSubscribed) => {
    console.log("Push subscribed:", isPushSubscribed);
});

권한 요청 시점

여기 또 큰 함정 — 앱 시작 즉시 push 권한 요청 = 큰 실수. 사용자가 왜 받아야 하는지 모르고 거부 → 영구히 (또는 OS 설정 변경 전까지) 알림 X.

좋은 권한 요청 패턴:

1. Soft prompt 먼저 — 자체 UI 로 "알림으로 좋은 정보 보낼게요" 동의 확인
2. 사용자가 가치 느낀 후 — 첫 결제 · 첫 follow · 첫 가입 완료 등 후
3. 그 다음 OS prompt — OS 의 표준 권한 다이얼로그

거부율 50% → 20% 까지 떨어뜨릴 수 있는 표준 운영 패턴.

자주 만나는 사고 — Identity · 데이터 모델

사고 1: Sequential ID 의 enumeration 공격

원인 — External ID = user.id (BIGINT 1, 2, 3, ...) + API key 노출.

해결 — UUID v4 또는 SHA-256 hash. 또는 최소 API key rotation.

사고 2: Anonymous → 기존 ID merge 가정

원인 — 로그인 후 이전 anonymous 활동 이 자동 merge 가정.

해결 — anonymous 가 완전 신규 user 인 경우만 merge. 기존 user 재로그인 = 별도 Identity Merge API 필요.

사고 3: Logout 시 changeUser 호출

원인 — 깨끗한 상태 만들려고 logout 시 changeUser(null).

해결 — 절대 X. SDK 가 자연스럽게 처리. 다음 로그인 시 changeUser(newId) 만.

사고 4: Shared default ID

원인 — 모든 anonymous 에게 같은 default ID 부여 → 데이터 통합.

해결 — anonymous 는 Braze 가 자동 부여 (changeUser 호출 X) + 필요 시 device-specific Alias.

사고 5: Attribute cardinality 폭증

원인 — signup_timestamp 같은 unique 값 attribute.

해결 — 분류 가능한 값만 attribute. 고유 값 = event property 또는 외부 시스템.

사고 6: Purchase 를 Custom Event 로

원인 — logCustomEvent("purchase", {amount: 50000}).

해결 — Purchase 는 항상 logPurchase. LTV 자동 분석.

사고 7: 앱 시작 즉시 push permission

원인 — requestPushPermission() 을 app launch 시점에 호출 → 큰 거부율.

해결 — Soft prompt → 가치 인식 → OS prompt 의 3 단계.

사고 8: SDK sync 안 됨

원인 — changeUser 호출 후 즉시 앱 종료 → buffer 데이터 손실.

해결 — 결제 같은 critical event = Server side 동시 추적. 또는 flushData() 명시 호출.

사고 9: User Alias 와 External ID 혼동

원인 — Alias 만 박고 External ID 안 박음 → API 일부 기능 제한.

해결 — 가능하면 External ID. Alias 는 부가 식별.

운영 권장 패턴

Pattern 1: Identity 결정 — 가입 시점

// 가입 완료 시 (회원가입 직후)
async function onSignupCompleted(userInput) {
    const newUser = await api.signup(userInput);

    // External ID = UUID v4 (서버에서 생성)
    const externalId = newUser.id;  // 또는 별도 UUID

    // Braze 에 사용자 연결 (anonymous 활동 merge)
    braze.changeUser(externalId);

    // 초기 attribute sync
    braze.getUser().setEmail(newUser.email);
    braze.getUser().setFirstName(newUser.firstName);
    braze.getUser().setCountry(newUser.country);
    braze.getUser().setLanguage(newUser.language);
    braze.getUser().setCustomAttribute("signup_year", new Date().getFullYear());
    braze.getUser().setCustomAttribute("tier", "free");

    // signup event
    braze.logCustomEvent("signup_completed", {
        source: userInput.source,
        referrer: userInput.referrer
    });
}

가입의 모든 데이터 가 한 함수에. 일관성.

Pattern 2: 재로그인 시 sync

// 이미 가입한 사용자 로그인
async function onLoginCompleted(user) {
    braze.changeUser(user.id);

    // 변경됐을 수 있는 attribute 만 sync
    braze.getUser().setEmail(user.email);
    braze.getUser().setCustomAttribute("tier", user.tier);
    braze.getUser().setCustomAttribute("last_login_date",
        new Date().toISOString());

    braze.openSession();
}

매 로그인 시 핵심 attribute 동기화 — Braze 의 데이터 최신성.

Pattern 3: Soft Push Permission

// 사용자가 *첫 결제* 같은 가치 인식 후
function showSoftPushPrompt() {
    // 자체 UI 모달
    showModal({
        title: "주문 진행 상황을 알려드릴까요?",
        body: "배송 · 할인 · 한정 상품 알림을 푸시로 받아 보세요",
        primary: {
            label: "네, 알림 받을게요",
            onClick: () => braze.requestPushPermission()
        },
        secondary: {
            label: "나중에",
            onClick: () => trackEvent("push_soft_dismissed")
        }
    });
}

거부율 50% → 20% 까지 개선.

Pattern 4: Server-side 안전망 (결제)

# Server: 결제 완료 webhook 처리
@app.post("/webhooks/order-completed")
async def on_order_completed(order: Order):
    # 1. 결제 처리
    await process_order(order)

    # 2. Braze 에 Purchase 동시 추적 (Client 가 누락해도 안전)
    for item in order.items:
        await braze_client.post("/users/track", json={
            "purchases": [{
                "external_id": order.user_id,
                "product_id": item.product_id,
                "currency": "KRW",
                "price": item.price,
                "quantity": item.quantity,
                "time": order.completed_at.isoformat()
            }]
        })

2편 의 Client + Server 동시 추적 의 백엔드 코드.

Pattern 5: User Alias 활용 — Legacy 마이그레이션

// 기존 legacy 시스템에서 마이그레이션
async function migrateLegacyUser(legacyUserId, newUserId) {
    // 1. 새 External ID 로 changeUser
    braze.changeUser(newUserId);

    // 2. Legacy ID 를 Alias 로 저장
    braze.getUser().addAlias(legacyUserId, "legacy_system");

    // → 이후 legacy_system + legacyUserId 로도 lookup 가능
    // → 마이그레이션 안 끝난 시스템과 호환
}

점진 마이그레이션의 표준 패턴.

Pattern 6: Anonymous 추적 정책

// 앱 진입 시 — 즉시 changeUser X
// (anonymous 상태 유지)

// 사용자 행동 추적 (anonymous)
braze.logCustomEvent("landing_viewed", { source: "google" });
braze.logCustomEvent("product_viewed", { product_id });

// 가입/로그인 시점에 changeUser
braze.changeUser(user.id);
// → 이전 anonymous 행동 자동 merge (new ID 의 경우)

anonymous 단계의 행동도 보존. 가입 funnel 의 모든 단계 분석.

시험 직전 한 번 더 — Developer Guide · Identity 함정 압축 노트

• Developer Guide 4 섹션 = Getting Started · Platform Integration · Features · Analytics & REST API
• 권장 학습 경로 5 단계 = SDK Overview → Integration Overview → 플랫폼 선택 → Initial Setup → 기능 모듈
• SDK 데이터 흐름 = SDK API → buffer → background sync → Braze Server → 메시지 발송
• 즉시 server 전송 X (buffer 지연)
• critical event = Server REST API 안전망 + flushData()
• External ID = 우리 시스템과 Braze 의 연결 키
• 없으면 = anonymous · API 기능 제한 · cross-device 분리
• changeUser() 4 동작:
• 같은 ID = 영향 X
• 다른 ID = 세션 종료 + 새 세션
• Anonymous → 새 ID = merge (자연스러운 가입 흐름)
• Anonymous → 기존 ID = merge 안 됨 ⚠️
• External ID 선택 기준:
• 좋음 = UUID v4 · SHA-256 hash · DB user.id (BIGINT)
• 나쁨 = sequential int (enumeration 공격) · email/phone (변경 가능) · session_id
• 보안 함정 — guessable ID + API key 유출 → 전체 user profile 노출
• User Alias = name + label 의 부가 식별자
• 사용 = anonymous targeting · legacy 마이그레이션 · CRM 매핑
• 절대 금지 2종:
• Shared default ID (공유 디바이스 통합)
• Logout 시 changeUser (anonymous 활동 손실 또는 잘못 통합)
• 데이터 모델 4 단위 = Custom Attribute · Custom Event · Purchase · Session
• Custom Attribute = 상태 (set · increment · array)
• 4 type = String · Number · Boolean · Array
• cardinality 통제 = 분류 가능한 값만, 고유 값은 event property
• sync 시점 = 로그인 · 정보 변경 · 첫 결제
• Custom Event = 행동 (timestamp · append-only · 누적)
• 동사_명사 + snake_case
• properties = JSON object (cardinality 통제)
• 한도 = event 당 properties 64 · 값 255자 정도
• Purchase = 결제 별도 모델 (LTV · ARPU · segment 자동)
• Custom Event 로 박으면 LTV 분석 X
• Server side 동시 추적 권장
• Session = SDK 자동 관리 (start · end · duration)
• 비활성 30초 후 종료 (SDK 설정)
• 활용 = retention segment · re-engagement
• Background Sync = 자동 + flushData() 명시 강제
• Push Token = iOS APNs · Android FCM · Web Service Worker
• 권한 요청 시점:
• 앱 시작 즉시 = 큰 실수 (50% 거부)
• 가치 인식 후 + Soft Prompt → OS Prompt 3 단계 권장
• 거부율 50% → 20% 개선 가능
• 사고 — Sequential ID 보안 · Anonymous→기존 merge 가정 · Logout changeUser · Shared default · Attribute cardinality · Purchase 를 Event · 앱 시작 push permission · SDK sync 손실 · Alias vs External ID 혼동
• 패턴 — Identity 결정 (가입 시점 sync 함수) · 재로그인 attribute sync · Soft Push Permission · Server-side 안전망 · Legacy Alias 마이그레이션 · Anonymous 추적 정책

공식 문서: Braze Developer Guide Home · Setting User IDs 에서 원문을 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 1편 — Customer Engagement Platform · 5 핵심 개념
• 2편 — SDK 통합 · REST API · 첫 캠페인 30분

다음 글:

• 4편 — Push · In-app · Content Card · Feature Flag
• 5편 — REST API 9 카테고리 · Messaging · Currents 깊이
• 6편 — Liquid · Connected Content · Personalization
• 7편 — Canvas · Campaign 운영 (마케터 관점)
• 8편 — 시리즈 마무리 · 도입 결정 · 경쟁 도구 · 학습 경로