Skip to content

CSV 가져오기

CSV 가져오기를 사용하여 사용자 속성 및 커스텀 이벤트를 기록하고 업데이트하는 방법을 알아보세요.

CSV 가져오기에 관하여

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을 사용하여 가져올 수 있습니다.

4단계: 파일 업로드

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

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

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

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

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

최대 허용 크기의 파일은 검증에 최대 2분이 소요될 수 있습니다. 검증 실행 중에 검증 건너뛰기를 선택하여 검증을 건너뛰고 즉시 진행할 수 있습니다.

검증 결과

검증이 완료되면 다음 결과 중 하나가 표시됩니다.

문제 발견 대화 상자에는 오류 및 경고가 포함된 행 수가 표시되며, 취소, 오류 보고서 다운로드 또는 어쨌든 가져오기 옵션이 제공됩니다.

오류 보고서 이해하기

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

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

6단계: 타겟팅 설정 선택

다음 타겟팅 설정 중에서 선택할 수도 있습니다. 가져오기에서 새로운 타겟팅 필터나 세그먼트를 생성할 필요가 없다면 이 목록을 타겟팅 필터로 사용 가능하게 하지 않음을 선택하세요.

"업데이트됨/CSV에서 가져옴" 필터를 포함하는 필터 그룹으로, "Halloween season fun"이라는 제목의 CSV 파일을 포함합니다.

7단계: CSV 가져오기 시작

준비가 되면 가져오기 시작을 선택하세요. 사용자 가져오기 페이지에서 현재 진행 상황을 확인할 수 있으며, 해당 페이지는 5초마다 자동으로 새로고침됩니다.

가져오기 상태

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

사용자 가져오기 페이지에 부분적 성공 상태가 표시되고 컨텍스트 메뉴가 열려 있으며, 오류 보고서 다운로드 및 업로드된 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 파일 선택 버튼이 작동하지 않을 수 있는 몇 가지 이유가 있습니다:
Github   GitHub 에서 이 페이지를 편집합니다.
New Stuff!