콘텐츠로 건너뛰기

변환 만들기

Braze 데이터 변환을 사용하면 웹훅 통합을 구축하고 관리하여 외부 플랫폼에서 Braze로 들어오는 데이터 흐름을 자동화할 수 있습니다. 이러한 웹훅 통합을 활용하면 더욱 정교한 마케팅 사용 사례를 구현할 수 있습니다. 기본 코드로 데이터 변환을 구축하거나, 특정 외부 플랫폼을 쉽게 시작할 수 있도록 마련된 전용 템플릿 라이브러리를 사용해 구축할 수 있습니다.

필수 조건

요구 사항 설명
2단계 인증 또는 SSO 계정에 2단계 인증(2FA) 또는 SSO(싱글 사인온)가 활성화되어 있어야 합니다.
올바른 권한 계정 관리자 또는 워크스페이스 관리자이거나 “변환 관리” 사용자 권한이 있어야 합니다.

1단계: 소스 플랫폼 식별

Braze에 연결하려는 외부 플랫폼을 식별하고 해당 플랫폼이 웹훅을 지원하는지 확인합니다. 이러한 설정은 ‘API 알림’ 또는 ‘웹 서비스 요청’이라고도 합니다.

다음은 Typeform 웹훅의 예시로, 해당 플랫폼에 로그인하여 구성할 수 있습니다.

Typeform 플랫폼 설정의 Typeform 웹훅 페이로드 예시.

2단계: 변환 만들기

Braze 대시보드에서 데이터 설정 > 데이터 변환으로 이동합니다.

변환 생성을 선택하여 변환 이름을 지정한 다음 편집 환경을 선택합니다.

편집 환경으로 "템플릿 사용" 또는 "처음부터 시작"을 선택할 수 있는 옵션이 있는 변환 세부 정보.

템플릿 사용을 선택하여 데이터 변환 사용 사례를 포함한 템플릿 라이브러리를 탐색합니다. 또는 처음부터 시작을 선택하여 기본 코드 템플릿을 로드합니다.

처음부터 시작하는 경우, 변환의 대상을 선택하세요. 템플릿 라이브러리에서 코드 템플릿을 삽입할 수도 있습니다.

대상에 대해 자세히 알아보기
  • POST: Track users: 소스 플랫폼의 웹훅을 속성, 이벤트 또는 구매와 같은 고객 프로필 업데이트로 변환합니다.
  • PUT: Update multiple catalog items: 소스 플랫폼의 웹훅을 카탈로그 항목 업데이트로 변환합니다.
  • DELETE: Delete multiple catalog items: 소스 플랫폼의 웹훅을 카탈로그 항목 삭제로 변환합니다.
  • PATCH: Edit multiple catalog items: 소스 플랫폼의 웹훅을 카탈로그 항목 편집으로 변환합니다.
  • POST: Send messages immediately via API Only: 소스 플랫폼의 웹훅을 변환하여 지정된 사용자에게 즉시 메시지를 전송합니다.

변환을 생성한 후 변환의 상세 보기가 표시됩니다. 여기에서 웹훅 세부 정보 아래에서 이 변환에 대해 가장 최근에 수신된 웹훅을 확인할 수 있으며, 변환 코드 아래에 변환 코드를 작성할 수 있는 공간이 있습니다.

다음 단계에서 사용할 웹훅 URL을 복사하세요.

이 단계는 선택 사항이지만, 소스 플랫폼에서 새로 만든 트랜스포메이션으로 테스트 웹훅을 보내는 것을 권장합니다.

  1. 트랜스포메이션에서 URL을 복사합니다.
  2. 소스 플랫폼에서 ‘테스트 보내기’ 기능을 찾아 이 URL로 보낼 샘플 웹훅을 생성합니다.
    • 소스 플랫폼에서 요청 유형을 묻는 경우 POST를 선택합니다.
    • 소스 플랫폼에서 인증 옵션을 제공하는 경우 인증 없음을 선택합니다.
    • 소스 플랫폼에서 시크릿을 요청하는 경우 시크릿 없음을 선택합니다.
  3. Braze 대시보드에서 페이지를 새로고침하여 웹훅이 수신되었는지 확인합니다. 웹훅이 수신되었다면 가장 최근 웹훅 아래에 웹훅 페이로드가 표시됩니다.

Typeform의 경우 다음과 같이 표시됩니다.

웹훅을 Braze 고객 프로필에 매핑하는 데이터 트랜스포메이션 코드 예시

4단계: 변환 코드 작성

JavaScript 코드 경험이 거의 없거나 더 자세한 안내가 필요하다면 Beginner - POST: Track users 또는 Beginner - PUT: Update multiple catalog items 탭을 따라 변환 코드를 작성하세요.

개발자이거나 JavaScript 코드 경험이 많다면 Advanced - POST: Track users 탭에서 변환 코드 작성에 관한 상위 수준의 안내를 확인하세요.

여기서는 다양한 웹훅 값을 Braze 고객 프로필에 매핑하는 방법을 정의하는 변환 코드를 작성합니다.

  1. 새 변환의 Transformation Code 섹션에는 다음과 같은 기본 템플릿이 있습니다.
// Here, we will define a variable, "brazecall", to build up a `/users/track` request
// Everything from the incoming webhook is accessible via the special variable "payload"
// So you can template in desired values in your `/users/track` request with dot notation, such as payload.x.y.z

let brazecall = {
  "attributes": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "attribute_1": payload.attribute_1
    }
  ],
  "events": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "name": payload.event_1,
      "time": new Date(),
      "properties": {
        "property_1": payload.event_1.property_1
      }
    }
  ],
  "purchases": [
    {
      "external_id": payload.user_id,
      "_update_existing_only": true,
      "product_id": payload.product_id,
      "currency": payload.currency,
      "price": payload.price,
      "quantity": payload.quantity,
      "time": payload.timestamp,
      "properties": {
        "property_1": payload.purchase_1.property_1
      }
    }
  ]
};

// After the /users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
  1. 변환 호출에 커스텀 속성, 커스텀 이벤트, 구매를 모두 포함하려면 3단계로 건너뛰세요. 그렇지 않으면 필요하지 않은 섹션을 삭제합니다.

  2. 각 속성, 이벤트, 구매 객체에는 external_id, user_alias, braze_id, email, phone 중 하나의 사용자 식별자가 필요합니다. 수신 웹훅의 페이로드에서 사용자 식별자를 찾아 페이로드 라인을 통해 변환 코드에 해당 값을 템플릿으로 넣으세요. 페이로드 객체 속성정보에 접근하려면 점 표기법을 사용합니다.

  3. 속성, 이벤트 또는 구매로 표현하려는 웹훅 값을 찾아 페이로드 라인을 통해 변환 코드에 해당 값을 템플릿으로 넣으세요. 페이로드 객체 속성정보에 접근하려면 점 표기법을 사용합니다.

  4. 각 속성, 이벤트, 구매 객체의 _update_existing_only 값을 확인하세요. 기본 템플릿에서는 이 값이 true로 설정되어 있어 기존 고객 프로필만 업데이트됩니다. 사용자가 존재하지 않을 때 새 사용자를 생성하려면 이 값을 false로 설정하세요. 객체에서 이 필드를 완전히 생략하면 false와 동일하게 동작합니다(새 사용자가 생성됨).

  5. Validate를 클릭하면 코드 출력의 미리보기를 확인하고 허용 가능한 /users/track 요청인지 검사할 수 있습니다.

  6. 변환을 활성화합니다. 활성화하기 전에 코드에 대한 추가 도움이 필요하면 Braze 계정 매니저에게 문의하세요.

  7. 소스 플랫폼에서 웹훅 전송을 시작하도록 합니다. 수신되는 각 웹훅에 대해 변환 코드가 실행되며, 고객 프로필 업데이트가 시작됩니다.

이제 웹훅 통합이 완료되었습니다!

여기서는 다양한 웹훅 값을 Braze 카탈로그 항목 업데이트에 매핑하는 방법을 정의하는 변환 코드를 작성할 수 있습니다.

  1. 새 변환의 Transformation Code 섹션에는 다음과 같은 기본 템플릿이 포함됩니다.
// This is a default template that you can use as a starting point
// Feel free to delete this entirely and create a new transformation, or edit specific components

// First, this code defines a variable, "brazecall", to build a PUT /catalogs/{catalog_name}/items request
// Everything from the incoming webhook is accessible via the special variable "payload"
// As such, you can template in desired values in your request with JS dot notation, such as payload.x.y.z

let brazecall = {
  // For Braze Data Transformation to update Catalog items, the special variable "catalog_name" is required
  // This variable is used to specify the catalog name which would otherwise go in the request URL
  "catalog_name": "catalog_name",

  // After defining "catalog name", construct the Update Multiple Catalog Items request as usual below
  // Documentation for the destination endpoint: /docs/ko/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/
  "items": [
    {
      "id": payload.item_id_1,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_2,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    },
    {
      "id": payload.item_id_3,
      "catalog_column1": "string",
      "catalog_column2": 1,
      "catalog_column3": true,
      "catalog_column4": "2021-09-03T09:03:19.967+00:00",
      "catalog_column5": {
        "Latitude": 33.6112,
        "Longitude": -117.8711
      }
    }
  ]
};

// After the request body is assigned to brazecall, you will want to explicitly return brazecall to create an output
return brazecall;
  1. /catalogs 대상에 대한 변환에는 업데이트할 특정 카탈로그를 정의하는 catalog_name이 필요합니다. 이 필드는 하드코딩하거나 페이로드 라인을 통해 웹훅 필드로 템플릿을 지정할 수 있습니다. 페이로드 객체 속성정보에 접근하려면 점 표기법을 사용합니다.

  2. items 배열의 id 필드로 카탈로그에서 업데이트할 항목을 정의합니다. 이러한 필드는 하드코딩하거나 페이로드 라인을 통해 웹훅 필드로 템플릿을 지정할 수 있습니다.

    catalog_column은 입력 안내 값이라는 점에 유의하세요. 항목 객체에는 카탈로그에 존재하는 필드만 포함되어야 합니다.

  3. Validate를 선택하면 코드 출력의 미리보기를 확인하고 여러 카탈로그 항목 업데이트 엔드포인트에 허용 가능한 요청인지 검사할 수 있습니다.

  4. 변환을 활성화합니다. 활성화하기 전에 코드에 대한 추가 도움이 필요하면 Braze 계정 매니저에게 문의하세요.

  5. 소스 플랫폼에 웹훅 전송을 시작하는 설정이 있는지 꼭 확인하세요. 수신되는 각 웹훅에 대해 변환 코드가 실행되며, 카탈로그 항목 업데이트가 시작됩니다.

이제 웹훅 통합이 완료되었습니다!

이 단계에서는 소스 플랫폼의 웹훅 페이로드를 JavaScript 객체 반환 값으로 변환합니다. 이 반환 값은 /users/track 엔드포인트 요청 본문 형식을 따라야 합니다.

  • 변환 코드는 JavaScript 프로그래밍 언어로 작성됩니다. if/else 로직과 같은 모든 표준 JavaScript 제어 흐름이 지원됩니다.
  • 변환 코드는 payload 변수를 통해 웹훅 요청 본문에 접근합니다. 이 변수는 요청 본문 JSON을 파싱하여 채워진 객체입니다.
  • /users/track 엔드포인트에서 지원되는 모든 기능이 지원되며, 여기에는 다음이 포함됩니다:
    • 사용자 속성 객체, 이벤트 객체, 구매 객체
    • 중첩 속성 및 중첩 커스텀 이벤트 속성정보
    • 구독 그룹 업데이트
    • 식별자로서의 이메일 주소

Validate를 선택하면 코드 출력의 미리보기를 확인하고 허용 가능한 /users/track 요청인지 검사할 수 있습니다.

5단계: 변환 모니터링

변환을 활성화한 후에는 기본 변환 페이지에서 분석 데이터를 확인해 성능 요약을 볼 수 있습니다.

  • 수신 요청: 이 변환의 URL로 수신된 웹훅 수입니다. 수신 요청이 0이면 소스 플랫폼에서 웹훅을 보내지 않았거나 연결을 설정할 수 없는 상태입니다.
  • 전달: 수신 요청을 받으면 데이터 변환이 변환 코드를 적용하여 선택한 Braze 대상으로 보냅니다.

수신 요청의 100%가 전달로 이어지도록 하는 것이 좋은 목표입니다. 전달 수는 수신 요청 수를 초과하지 않습니다.

문제 해결

더 자세한 모니터링과 문제 해결이 필요하면 로그 페이지에서 개별 로그를 확인하세요. 이 페이지에는 모든 워크스페이스의 모든 변환에 대한 최근 1,000건의 수신 요청이 기록됩니다. 각 로그를 선택하면 수신 요청 본문, 변환 출력, 변환 대상의 응답 본문을 볼 수 있습니다.

전달이 없다면 변환 코드에 구문 오류가 있는지 확인하고 코드가 정상적으로 컴파일되는지 확인하세요. 그런 다음 출력이 유효한 대상 요청인지 확인하세요.

전달 수가 수신 요청 수보다 적다면 적어도 일부 웹훅은 성공적으로 전달되고 있다는 뜻입니다. 변환 로그에서 오류 예시를 확인하고, 변환 출력이 예상한 대로인지 살펴보세요. 변환 코드가 수신되는 모든 웹훅 형태를 처리하지 못하고 있을 수 있습니다.

New Stuff!