Skip to content

CSV 가져오기

CSV 가져오기를 사용하여 사용자 속성과 커스텀 이벤트를 기록하고 업데이트하는 방법을 알아봅니다.

CSV 가져오기 소개

CSV 가져오기를 사용하여 다음 사용자 속성과 커스텀 이벤트를 기록하고 업데이트할 수 있습니다. Braze는 다음 표에 나와 있는 최대 크기 이내의 표준 CSV 파일로 이 데이터를 수신합니다.

CSV 가져오기 사용하기

1단계: CSV 템플릿 다운로드

CSV 가져오기를 열려면 오디언스 > 사용자 가져오기로 이동합니다. 여기에서 업로드 날짜, 업로더 이름, 파일 이름, 타겟팅 가용성, 가져온 행 수, 가져오기 상태 등 가장 최근 가져오기에 대한 세부 정보가 나열된 표를 확인할 수 있습니다.

CSV를 시작하려면 속성 또는 이벤트용 템플릿을 다운로드합니다.

Braze 대시보드의 '사용자 가져오기' 페이지.

2단계: 식별자 선택

가져올 CSV에는 전용 식별자가 필요합니다. 다음 중에서 선택할 수 있습니다:

고객 데이터를 가져올 때 external_id를 각 고객의 고유 식별자로 사용할 수 있습니다. 가져오기에서 external_id를 제공하면 Braze는 동일한 external_id를 가진 기존 사용자를 업데이트하거나, 해당 external_id가 없는 경우 해당 external_id가 설정된 새로 식별된 사용자를 생성합니다.

external_id가 없는 사용자를 타겟팅하려면 사용자 별칭이 포함된 사용자 목록을 가져올 수 있습니다. 별칭은 대체 고유 사용자 식별자 역할을 하며, 가입하지 않았거나 앱에서 계정을 만들지 않은 익명 사용자에게 마케팅하려는 경우 유용할 수 있습니다.

별칭 전용 사용자 프로필을 업로드하거나 업데이트하는 경우 CSV에 다음 두 열이 있어야 합니다:

  • user_alias_name: 고유 사용자 식별자로, external_id의 대안입니다.
  • user_alias_label: 사용자 별칭을 그룹화하는 공통 레이블입니다.

가져오기에서 user_alias_name과 user_alias_label을 모두 제공하면 Braze는 동일한 user_alias_name과 user_alias_label을 가진 기존 사용자를 업데이트합니다. 사용자를 찾을 수 없는 경우 Braze는 해당 user_alias_name이 설정된 새로 식별된 사용자를 생성합니다.

다운로드: CSV 속성 가져오기 템플릿: 사용자 별칭

external_id 또는 user_alias_name과 user_alias_label 값 대신 내부 Braze ID 값을 사용하여 Braze에서 기존 사용자 프로필을 업데이트하려면 braze_id를 열 헤더로 지정합니다.

이 방법은 세분화 내 CSV 내보내기 옵션을 통해 Braze에서 사용자 데이터를 내보낸 후 해당 기존 사용자에게 새 커스텀 속성을 추가하려는 경우 유용할 수 있습니다.

외부 ID 또는 사용자 별칭을 생략하고 이메일 주소 또는 전화번호를 사용하여 사용자를 가져올 수 있습니다. 이메일 주소 또는 전화번호가 포함된 CSV 파일을 가져오기 전에 다음 사항을 확인합니다:

  • CSV 파일에 이러한 프로필에 대한 외부 ID 또는 사용자 별칭이 없는지 확인합니다. 있는 경우 Braze는 프로필을 식별할 때 이메일 주소보다 외부 ID 또는 사용자 별칭을 우선적으로 사용합니다.
  • CSV 파일이 올바르게 포맷되었는지 확인합니다.

해당 이메일 주소 또는 전화번호를 가진 기존 프로필이 있으면 해당 프로필이 업데이트되며, Braze는 새 프로필을 생성하지 않습니다. 동일한 이메일 주소를 가진 프로필이 여러 개 있는 경우 Braze는 /users/track 엔드포인트와 동일한 로직을 사용하여 가장 최근에 업데이트된 프로필을 업데이트합니다.

해당 이메일 주소 또는 전화번호를 가진 프로필이 존재하지 않으면 Braze는 해당 식별자로 새 프로필을 생성합니다. /users/identify 엔드포인트를 사용하여 나중에 이 프로필을 식별할 수 있습니다. 사용자 프로필을 삭제하려면 /users/delete 엔드포인트를 사용할 수도 있습니다.

3단계: CSV 파일 작성

다음 데이터 유형 중 하나를 단일 CSV 파일로 업로드할 수 있습니다. 둘 이상의 데이터 유형을 업로드하려면 여러 CSV 파일을 업로드합니다.

  • 사용자 속성: 기본 및 커스텀 사용자 속성을 모두 포함합니다. 기본 사용자 속성은 Braze의 예약 키(예: first_name 또는 email)이며, 커스텀 속성은 비즈니스에 고유한 사용자 속성(예: last_destination_searched)입니다.
  • 커스텀 이벤트: 비즈니스에 고유하며 사용자가 수행한 행동을 반영합니다. 예를 들어 여행 예약 앱의 경우 trip_booked가 있습니다.

CSV 파일 작성을 시작할 준비가 되면 다음 정보를 참조합니다:

필수 식별자

external_id는 필수가 아니지만 CSV 파일의 헤더에 다음 식별자 중 하나를 반드시 포함해야 합니다. 각 식별자에 대한 자세한 내용은 식별자 선택을 참조합니다.

  • external_id
  • braze_id
  • user_alias_name 및 user_alias_label
  • email
  • phone

커스텀 속성

다음 데이터 유형을 CSV 가져오기의 커스텀 속성으로 사용할 수 있습니다. 기본 속성과 정확히 일치하지 않는 열 헤더는 Braze에서 커스텀 속성으로 가져옵니다.

기본 속성

다음 기본 속성을 사용자 가져오기에 사용할 수 있습니다.

구독 그룹 상태 업데이트(선택 사항)

또한 사용자 가져오기를 통해 이메일 또는 SMS 구독 그룹에 사용자를 추가할 수 있습니다. 이는 SMS 채널로 메시지를 보내려면 사용자가 SMS 구독 그룹에 등록되어 있어야 하므로 SMS에 특히 유용합니다. 자세한 내용은 SMS 구독 그룹을 참조합니다.

구독 그룹 상태를 업데이트하는 경우 CSV에 다음 두 열이 있어야 합니다:

  • subscription_group_id: 구독 그룹의 id입니다.
  • subscription_state: 사용 가능한 값은 unsubscribed(구독 그룹에 없음) 또는 subscribed(구독 그룹에 있음)입니다.

필수 식별자

external_id는 필수가 아니지만 CSV 파일의 헤더에 다음 식별자 중 하나를 반드시 포함해야 합니다. 각 식별자에 대한 자세한 내용은 식별자 선택을 참조합니다.

  • external_id
  • braze_id
  • user_alias_name 및 user_alias_label
  • email
  • phone

커스텀 이벤트 필드

다음 외에도 CSV에 이벤트 속성정보에 대한 추가 열 헤더를 포함할 수 있습니다. 이러한 속성정보의 열 헤더는 <event_name>.properties.<property name> 형식이어야 합니다.

예를 들어 커스텀 이벤트 trip_booked에 destination과 duration 속성정보가 있을 수 있습니다. 이는 열 헤더 trip_booked.properties.destination과 trip_booked.properties.duration을 사용하여 가져올 수 있습니다.

커스텀 이벤트 포맷 요구 사항

CSV를 사용하여 커스텀 이벤트를 가져올 때 데이터 가져오기를 성공적으로 수행하려면 다음 요구 사항에 따라 파일을 포맷해야 합니다.

커스텀 이벤트 포맷 이해하기

각 속성정보가 올바른 이벤트에 매핑되도록 점 표기법을 사용하여 커스텀 이벤트 CSV를 올바르게 포맷하는 것이 중요합니다. 포맷이 올바르지 않으면 속성정보가 누락되거나 가져오기가 실패할 수 있으며, 특히 하나의 파일에 여러 이벤트 유형이 포함된 경우 더욱 그렇습니다.

이벤트 속성정보에 점 표기법 사용

점 표기법은 커스텀 이벤트와 해당 속성정보 간의 계층적 관계를 정의하는 데 사용됩니다. 이 포맷 규칙을 사용하면 각 이벤트에 대한 특정 속성을 포함하는 구조화된 이벤트 데이터를 가져올 수 있습니다.

점 표기법 형식은 다음 구조를 따릅니다: event_name.properties.property_name

점 표기법은 다음 순서로 작동합니다:

  1. 이벤트 이름이 먼저 옵니다
  2. 그 다음 .properties.가 와서 뒤따르는 것이 이벤트 속성정보임을 나타냅니다
  3. 마지막으로 특정 속성정보 이름이 옵니다

예시:

rented_movie라는 커스텀 이벤트에 movie_name과 genre 속성정보가 있는 경우 CSV 열 헤더는 다음과 같습니다:

  • rented_movie.properties.movie_name
  • rented_movie.properties.genre

이 표기법은 Braze에 rented_movie라는 커스텀 이벤트를 생성하고 해당 특정 이벤트 인스턴스에 movie_name과 genre 속성정보를 첨부하도록 지시합니다.

행당 하나의 이벤트

CSV의 각 행은 단일 사용자에 대한 단일 커스텀 이벤트를 나타냅니다. 사용자에게 여러 이벤트가 있는 경우 동일한 사용자 식별자를 공유하더라도 각 이벤트에 대해 별도의 행을 포함해야 합니다.

CSV 구조 예시

다음 표는 속성정보가 있는 커스텀 이벤트를 가져오기 위한 올바른 포맷을 보여줍니다. 이 예시에서는 각각 다른 이벤트를 수행한 두 명의 사용자를 보여줍니다: 한 명은 영화를 대여했고, 다른 한 명은 영화를 구매했습니다.

이 예시에서:

  • 사용자 123은 movie_name(Ghostbusters)과 genre(Action) 속성정보가 있는 rented_movie 이벤트를 트리거했습니다
  • 사용자 456은 movie_name(Ghostbusters)과 genre(Action) 속성정보가 있는 bought_movie 이벤트를 트리거했습니다
  • 각 이벤트는 관련 속성정보 열만 채우고 다른 이벤트 속성정보 열은 비워 둡니다

4단계: 파일 업로드

파일을 업로드하려면 속성 또는 이벤트를 선택하고 파일 찾기를 클릭한 다음 CSV를 업로드합니다. Braze는 처음 몇 행의 미리보기와 감지된 필드의 요약을 표시합니다.

대용량 파일(기본 속성 및 커스텀 속성의 경우 최대 500 MB, 커스텀 이벤트의 경우 최대 50 MB)의 경우 파일이 업로드되고 Braze가 가져오기를 계산하는 동안 대시보드가 일시적으로 응답하지 않는 것처럼 보일 수 있습니다. 이러한 업로드 및 계산은 작은 파일보다 완료하는 데 더 오래 걸릴 수 있습니다. 이 단계가 완료될 때까지 기다립니다. 파일 제한 및 타이밍에 대한 자세한 내용은 CSV 구성하기를 참조합니다.

파일 미리보기, 가져오기 이름 필드, 타겟팅 기본 설정 및 파일 유효성 검사 체크박스가 표시된 업로드 완료 모달.

가져오기 이름 필드에서 가져오기 이름을 변경할 수 있습니다. 기본적으로 파일 이름이 사용됩니다.

5단계: 파일 유효성 검사(선택 사항)

가져오기를 시작하기 전에 파일 유효성 검사를 실행하여 모든 행에서 오류와 경고를 확인할 수 있습니다. 파일의 유효성을 검사하려면 가져오기 전 파일 유효성 검사를 선택한 다음 가져오기 시작을 클릭합니다.

유효성 검사는 최대 허용 크기의 파일에 대해 최대 2분이 소요될 수 있습니다. 유효성 검사가 실행되는 동안 유효성 검사 건너뛰기를 선택하여 건너뛰고 즉시 진행할 수 있습니다.

유효성 검사 결과

유효성 검사가 완료되면 다음 결과 중 하나가 나타납니다.

오류 및 경고가 있는 행 수를 표시하고 취소, 오류 보고서 다운로드 또는 그래도 가져오기 옵션이 있는 문제 발견 대화 상자.

오류 보고서 이해하기

오류 보고서는 플래그가 지정된 모든 행과 원본 데이터 및 문제 설명이 포함된 CSV 파일입니다.

보고서를 검토한 후 원본 파일에서 문제를 수정하고 다시 업로드하거나, 가져오기를 진행하고 부분 결과를 수락할 수 있습니다.

6단계: 타겟팅 기본 설정 선택

다음 타겟팅 기본 설정 중에서 선택할 수도 있습니다. 가져오기에서 새 타겟팅 필터나 Segment를 만들 필요가 없는 경우 이 목록을 타겟팅 필터로 사용하지 않음을 선택합니다.

"Halloween season fun"이라는 CSV 파일이 포함된 "CSV에서 업데이트/가져오기" 필터가 있는 필터 그룹.

7단계: CSV 가져오기 시작

준비가 되면 가져오기 시작을 선택합니다. 사용자 가져오기 페이지에서 현재 진행 상황을 추적할 수 있으며, 5초마다 자동으로 새로고침됩니다. CSV 크기에 따라 처리에 몇 분에서 몇 시간이 걸릴 수 있습니다. 이 시간 동안 대시보드가 응답하지 않거나 느리게 응답할 수 있지만 가져오기는 계속 실행됩니다.

가져오기 상태

가져오기를 시작한 후 사용자 가져오기 페이지에서 상태를 확인할 수 있습니다.

부분 성공 상태가 표시된 사용자 가져오기 페이지에서 컨텍스트 메뉴가 열려 있고 오류 보고서 다운로드 및 업로드된 CSV 다운로드 옵션이 표시됩니다.

가져오기 후 오류 보고서에는 유효성 검사에서 다루지 않는 이유로 실패한 행이 포함됩니다. 예를 들어 Braze에 사용자가 존재하지 않는 경우입니다.

데이터 포인트 고려 사항

CSV 파일에서 가져온 각 고객 데이터는 사용자 프로필의 기존 값을 덮어쓰고 데이터 포인트를 기록합니다. 단, 외부 ID와 빈 값은 예외입니다. Braze 데이터 포인트의 세부 사항에 대해 궁금한 점이 있으면 Braze 계정 매니저에게 문의할 수 있습니다.

문제 해결

파일 유효성 검사를 사용한 경우 오류 보고서부터 시작합니다. 오류 보고서에는 플래그가 지정된 각 행에 대한 구체적인 문제와 수정 방법에 대한 설명이 포함되어 있습니다. 유효성 검사가 아닌 가져오기 중에 실패한 행의 경우 사용자 가져오기 페이지에서 행 위에 마우스를 올리고 버튼을 선택하여 오류 보고서를 다운로드합니다.

CSV 가져오기 문제 해결을 위해 아래의 일반적인 문제를 검토합니다.

파일 포맷 문제

잘못된 형식의 행

업로드가 오류와 함께 완료된 경우 CSV 파일에 잘못된 형식의 행이 있을 수 있습니다.

데이터를 올바르게 가져오려면 헤더 행이 있어야 합니다. 각 행은 헤더 행과 동일한 수의 셀을 가져야 합니다. 헤더 행보다 값이 많거나 적은 행은 가져오기에서 제외됩니다. 값 내의 쉼표는 구분 기호로 해석되어 이 오류를 유발할 수 있습니다. 또한 모든 데이터는 UTF-8로 인코딩되어야 합니다.

CSV 파일에 빈 행이 있고 CSV 파일의 총 줄 수보다 적은 행이 가져와진 경우 빈 행은 가져올 필요가 없으므로 가져오기에 문제가 있는 것이 아닐 수 있습니다. 올바르게 가져온 줄 수를 확인하고 가져오려는 사용자 수와 일치하는지 확인합니다.

누락된 행

가져온 사용자 수가 CSV 파일의 총 행 수와 일치하지 않는 데에는 몇 가지 이유가 있습니다:

문자열 따옴표

작은따옴표('') 또는 큰따옴표("")로 감싸진 값은 가져오기 시 문자열로 읽힙니다.

잘못된 형식의 날짜

ISO-8601 형식이 아닌 날짜는 가져오기 시 datetimes로 읽히지 않습니다.

데이터 구조 문제

잘못된 이메일 주소

업로드가 오류와 함께 완료된 경우 하나 이상의 잘못된 암호화된 이메일 주소가 있을 수 있습니다. Braze로 가져오기 전에 모든 이메일 주소가 올바르게 암호화되었는지 확인합니다.

  • Braze에서 이메일 주소를 업데이트하거나 가져올 때 이메일이 포함된 모든 곳에서 해시된 이메일 값을 사용합니다. 이러한 해시 이메일 값은 내부 팀에서 제공합니다.
  • 새 사용자를 생성할 때 사용자의 암호화된 이메일 값과 함께 email_encrypted를 추가해야 합니다. 그렇지 않으면 Braze가 사용자를 생성하지 않습니다. 마찬가지로 이메일이 없는 기존 사용자에게 이메일 주소를 추가하는 경우 email_encrypted를 추가해야 합니다. 그렇지 않으면 Braze가 사용자를 업데이트하지 않습니다.

커스텀 속성으로 가져온 데이터

기본 사용자 데이터(예: email 또는 first_name)가 커스텀 속성으로 가져와진 경우 CSV 파일의 대소문자와 간격을 확인합니다. 예를 들어 First_name은 커스텀 속성으로 가져오지만 first_name은 사용자 프로필의 “이름” 필드에 올바르게 가져옵니다.

커스텀 속성의 데이터 유형 변경

기존 커스텀 속성의 데이터 유형을 변경해야 하는 경우(예: 문자열에서 부울로) CSV를 가져오기 전에 대시보드의 커스텀 속성 페이지에서 데이터 유형을 업데이트합니다. CSV의 데이터 유형이 속성의 현재 정의된 데이터 유형과 일치하지 않으면 가져오기가 오류와 함께 실패합니다.

여러 데이터 유형

Braze는 열의 각 값이 동일한 데이터 유형일 것으로 예상합니다. 속성의 데이터 유형과 일치하지 않는 값은 세분화 시 오류를 유발합니다.

또한 숫자 속성을 0으로 시작하면 0으로 시작하는 숫자가 문자열로 간주되므로 문제가 발생합니다. Braze가 해당 문자열을 변환할 때 8진수 값(0에서 7까지의 숫자를 사용)으로 처리될 수 있으며, 이는 해당 10진수 값으로 변환됩니다. 예를 들어 CSV 파일의 값이 0130이면 Braze 프로필에는 88이 표시됩니다. 이 문제를 방지하려면 문자열 데이터 유형의 속성을 사용합니다. 그러나 이 데이터 유형은 세분화 숫자 비교에서 사용할 수 없습니다.

기본 속성 유형

일부 기본 속성은 사용자 업데이트에 유효한 특정 값만 허용할 수 있습니다. 지침은 CSV 구성하기를 참조합니다.

후행 공백과 대소문자 차이로 인해 값이 유효하지 않은 것으로 해석될 수 있습니다. 예를 들어 다음 CSV 파일에서 첫 번째 행의 사용자(brazetest1)만 이메일 및 푸시 상태가 성공적으로 업데이트됩니다. 허용되는 값은 unsubscribed, subscribed, opted_in이기 때문입니다.

1
2
3

external_id,email,email_subscribe,push_subscribe
brazetest1,[email protected],unsubscribed,unsubscribed
brazetest2,[email protected],Unsubscribed,Unsubscribed

“CSV 파일 선택”이 작동하지 않음

CSV 파일 선택 버튼이 작동하지 않는 데에는 여러 가지 이유가 있습니다:
New Stuff!