Skip to content

CSVインポート

CSVインポートを使用してユーザー属性やカスタムイベントを記録・更新する方法を説明します。

CSVインポートについて

CSVインポートを使用して、以下のユーザー属性やカスタムイベントを記録・更新できます。Brazeは、以下の表に記載された最大サイズ以内の標準CSVファイルとしてこのデータを受け付けます。

CSVインポートの使用

ステップ 1:CSVテンプレートをダウンロードする

CSVインポートを開くには、Audiences > Import Users に移動します。ここには、アップロード日、アップロード者名、ファイル名、ターゲティングの利用可否、インポートされた行数、インポートのステータスなど、最新のインポートに関する詳細を一覧表示するテーブルがあります。

CSVの作成を始めるには、属性またはイベント用のテンプレートをダウンロードしてください。

Brazeダッシュボードの「Import Users」ページ。

ステップ 2:識別子を選択する

インポートするCSVには、専用の識別子が必要です。以下から選択できます。

顧客データをインポートする際、各顧客の一意の識別子としてexternal_idを使用できます。インポートでexternal_idを指定すると、Brazeは同じexternal_idを持つ既存のユーザーを更新するか、該当するユーザーが見つからない場合はそのexternal_idが設定された新しい識別済みユーザーを作成します。

external_idを持たないユーザーをターゲットにするには、ユーザーエイリアスを使用してユーザーのリストをインポートできます。エイリアスは代替の一意のユーザー識別子として機能し、サインアップやアカウント作成をしていない匿名ユーザーにマーケティングを行う場合に役立ちます。

エイリアスのみのユーザープロファイルをアップロードまたは更新する場合、CSVに以下の2つの列が必要です。

  • 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からユーザーデータをエクスポートし、それらの既存ユーザーに新しいカスタム属性を追加したい場合に便利です。

external IDやユーザーエイリアスを省略し、メールアドレスまたは電話番号を使用してユーザーをインポートできます。メールアドレスまたは電話番号を含むCSVファイルをインポートする前に、以下を確認してください。

  • CSVファイルにこれらのプロファイルのexternal IDやユーザーエイリアスが含まれていないことを確認してください。含まれている場合、Brazeはプロファイルの識別にメールアドレスよりもexternal IDまたはユーザーエイリアスを優先します。
  • CSVファイルが正しくフォーマットされていることを確認してください。

そのメールアドレスまたは電話番号を持つ既存のプロファイルがある場合、そのプロファイルが更新され、Brazeは新しいプロファイルを作成しません。同じメールアドレスを持つ複数のプロファイルがある場合、Brazeは/users/trackエンドポイントと同じロジックを使用し、最も最近更新されたプロファイルが更新されます。

そのメールアドレスまたは電話番号を持つプロファイルが存在しない場合、Brazeはその識別子を持つ新しいプロファイルを作成します。/users/identifyエンドポイントを使用して、後でこのプロファイルを識別できます。ユーザープロファイルを削除するには、/users/deleteエンドポイントも使用できます。

ステップ 3:CSVファイルを作成する

以下のいずれかのデータタイプを1つのCSVファイルとしてアップロードできます。複数のデータタイプをアップロードするには、複数のCSVファイルをアップロードしてください。

  • ユーザー属性：デフォルトとカスタムの両方のユーザー属性が含まれます。デフォルトのユーザー属性はBrazeの予約キー（first_nameやemailなど）であり、カスタム属性はビジネス固有のユーザー属性（last_destination_searchedなど）です。
  • カスタムイベント：ビジネス固有のイベントで、旅行予約アプリのtrip_bookedのように、ユーザーが実行したアクションを表します。

CSVファイルの作成を始める準備ができたら、以下の情報を参照してください。

必須の識別子

external_idは必須ではありませんが、CSVファイルのヘッダーとして以下の識別子のうち1つを必ず含める必要があります。各識別子の詳細については、識別子を選択するを参照してください。

  • external_id
  • braze_id
  • user_alias_name および user_alias_label
  • email
  • phone

カスタム属性

以下のデータタイプは、CSVインポートのカスタム属性として使用できます。デフォルト属性と完全に一致しない列ヘッダーは、Brazeでカスタム属性としてインポートされます。

デフォルト属性

以下のデフォルト属性がユーザーインポートで利用可能です。

サブスクリプショングループのステータスを更新する（オプション）

さらに、ユーザーインポートを通じてメールまたはSMSのサブスクリプショングループにユーザーを追加できます。これはSMSの場合に特に便利です。SMSチャネルでメッセージを送信するには、ユーザーがSMSサブスクリプショングループに登録されている必要があるためです。詳細については、SMSサブスクリプショングループを参照してください。

サブスクリプショングループのステータスを更新する場合、CSVに以下の2つの列が必要です。

  • subscription_group_id：サブスクリプショングループのid。
  • subscription_state：利用可能な値はunsubscribed（サブスクリプショングループに含まれない）またはsubscribed（サブスクリプショングループに含まれる）です。

必須の識別子

external_idは必須ではありませんが、CSVファイルのヘッダーとして以下の識別子のうち1つを必ず含める必要があります。各識別子の詳細については、識別子を選択するを参照してください。

  • 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を正しくフォーマットすることが重要です。フォーマットが正しくない場合、プロパティが欠落したり、特に1つのファイルに複数のイベントタイプが含まれている場合にインポートが失敗したりする可能性があります。

イベントプロパティにドット記法を使用する

ドット記法は、カスタムイベントとそのプロパティの階層関係を定義するために使用されます。このフォーマット規則により、各イベントの特定の属性を含む構造化されたイベントデータをインポートできます。

ドット記法の形式は次の構造に従います：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を付加します。

1行につき1イベント

CSVの各行は、1人のユーザーの1つのカスタムイベントを表します。ユーザーに複数のイベントがある場合、同じユーザー識別子を共有していても、各イベントに対して別々の行を含める必要があります。

CSVの構造例

以下の表は、プロパティを持つカスタムイベントをインポートするための正しいフォーマットを示しています。この例では、2人のユーザーがそれぞれ異なるイベントを実行しています。1人は映画をレンタルし、もう1人は映画を購入しました。

この例では：

  • ユーザー123がプロパティmovie_name（Ghostbusters）とgenre（Action）を持つrented_movieイベントをトリガーしました
  • ユーザー456がプロパティmovie_name（Ghostbusters）とgenre（Action）を持つbought_movieイベントをトリガーしました
  • 各イベントは関連するプロパティ列のみを入力し、他のイベントプロパティ列は空白のままにしています

ステップ 4:ファイルをアップロードする

ファイルをアップロードするには、AttributesまたはEventsを選択し、Browse FilesをクリックしてCSVをアップロードします。Brazeは最初の数行のプレビューと検出されたフィールドの概要を表示します。

大きなファイル（デフォルト属性とカスタム属性は最大500 MB、カスタムイベントは最大50 MB）の場合、ファイルのアップロードとBrazeによるインポートの計算中にダッシュボードが一時的に応答しなくなることがあります。これらのアップロードと計算は、小さなファイルよりも完了に時間がかかる場合があります。このステップが完了するまでお待ちください。ファイルの制限とタイミングの詳細については、CSVの構築を参照してください。

ファイルプレビュー、インポート名フィールド、ターゲティング設定、ファイル検証チェックボックスを表示するアップロード完了モーダル。

Import nameフィールドで、インポートの名前を変更できます。デフォルトではファイル名が使用されます。

ステップ 5:ファイルを検証する（オプション）

インポートを開始する前に、ファイル検証を実行してすべての行のエラーと警告を確認できます。ファイルを検証するには、Validate file before importingを選択し、Start importをクリックします。

検証は最大許容サイズのファイルで最大2分かかる場合があります。検証の実行中に、Skip validationを選択して検証をバイパスし、すぐに進めることもできます。

検証結果

検証が完了すると、以下のいずれかの結果が表示されます。

エラーと警告のある行数を表示し、キャンセル、エラーレポートのダウンロード、またはインポート続行のオプションがある問題検出ダイアログ。

エラーレポートについて

エラーレポートは、フラグが付けられたすべての行とその元のデータ、および問題の説明を含むCSVファイルです。

レポートを確認した後、元のファイルの問題を修正して再アップロードするか、インポートを続行して部分的な結果を受け入れることができます。

ステップ 6:ターゲティング設定を選択する

以下のターゲティング設定から選択することもできます。インポートから新しいターゲティングフィルターやSegmentを作成する必要がない場合は、Do not make this list available as a targeting filterを選択してください。

「Halloween season fun」というCSVファイルを含む「Updated/Imported from CSV」フィルターを使用したフィルターグループ。

ステップ 7:CSVインポートを開始する

準備ができたら、Start importを選択します。Import Usersページで現在の進捗状況を追跡できます。このページは5秒ごとに自動更新されます。処理はCSVのサイズに応じて数分から数時間かかる場合があります。この間、ダッシュボードが応答しなくなったり、応答が遅くなったりすることがありますが、インポートは引き続き実行されています。

インポートステータス

インポートを開始した後、Import Usersページでステータスを確認できます。

「一部成功」ステータスが表示されたImport Usersページ。コンテキストメニューが開き、エラーレポートのダウンロードとアップロードされたCSVのダウンロードオプションが表示されています。

インポート後のエラーレポートには、検証ではカバーされない理由で失敗した行が含まれます。例えば、Brazeにユーザーが存在しない場合などです。

データポイントに関する考慮事項

CSVファイルからインポートされた各顧客データは、ユーザープロファイルの既存の値を上書きし、データポイントとして記録されます。ただし、external IDと空白の値は除きます。Brazeのデータポイントの詳細について質問がある場合は、Brazeアカウントマネージャーにお問い合わせください。

トラブルシューティング

ファイル検証を使用した場合は、エラーレポートから始めてください。フラグが付けられた各行の具体的な問題と修正方法の説明が含まれています。検証ではなくインポート中に失敗した行については、Import Usersページで行にカーソルを合わせ、ボタンを選択してエラーレポートをダウンロードしてください。

CSVインポートのトラブルシューティングについては、以下の一般的な問題を確認してください。

ファイルフォーマットの問題

不正な行

アップロードがエラーで完了した場合、CSVファイルに不正な行がある可能性があります。

データを正しくインポートするには、ヘッダー行が必要です。各行はヘッダー行と同じ数のセルを持つ必要があります。ヘッダー行よりも値が多いまたは少ない行はインポートから除外されます。値内のカンマは区切り文字として解釈され、このエラーの原因となる可能性があります。また、すべてのデータはUTF-8エンコードである必要があります。

CSVファイルに空白行があり、CSVファイルの合計行数よりも少ない行数がインポートされた場合、空白行はインポートする必要がないため、インポートに問題があるとは限りません。正しくインポートされた行数を確認し、インポートしようとしているユーザー数と一致していることを確認してください。

行の欠落

インポートされたユーザー数がCSVファイルの合計行数と一致しない理由はいくつかあります。

文字列の引用符

シングルクォート（''）またはダブルクォート（""）で囲まれた値は、インポート時に文字列として読み取られます。

不正なフォーマットの日付

ISO-8601形式でない日付は、インポート時にdatetimesとして読み取られません。

データ構造の問題

無効なメールアドレス

アップロードがエラーで完了した場合、1つ以上の無効な暗号化メールアドレスがある可能性があります。Brazeにインポートする前に、すべてのメールアドレスが正しく暗号化されていることを確認してください。

  • Brazeでメールアドレスを更新またはインポートする場合、メールが含まれるすべての場所でハッシュ化されたメール値を使用してください。これらのハッシュメール値は社内チームから提供されます。
  • 新しいユーザーを作成する場合、ユーザーの暗号化メール値を含むemail_encryptedを追加する必要があります。そうしないと、Brazeはユーザーを作成しません。同様に、メールを持たない既存のユーザーにメールアドレスを追加する場合は、email_encryptedを追加する必要があります。そうしないと、Brazeはユーザーを更新しません。

カスタム属性としてインポートされたデータ

デフォルトのユーザーデータ（emailやfirst_nameなど）がカスタム属性としてインポートされた場合、CSVファイルの大文字小文字とスペースを確認してください。例えば、First_nameはカスタム属性としてインポートされますが、first_nameはユーザープロファイルの「名」フィールドに正しくインポートされます。

カスタム属性のデータタイプを変更する

既存のカスタム属性のデータタイプを変更する必要がある場合（例：文字列からブール値へ）、CSVをインポートする前にダッシュボードのカスタム属性ページでデータタイプを更新してください。CSVのデータタイプが属性の現在定義されているデータタイプと一致しない場合、インポートはエラーで失敗します。

複数のデータタイプ

Brazeは列内の各値が同じデータタイプであることを期待しています。属性のデータタイプと一致しない値は、セグメンテーションでエラーの原因となります。

さらに、数値属性をゼロで始めると問題が発生します。ゼロで始まる数値は文字列と見なされるためです。Brazeがその文字列を変換する際、8進数値（0から7の数字を使用）として扱われる可能性があり、対応する10進数値に変換されます。例えば、CSVファイルの値が0130の場合、Brazeプロファイルには88と表示されます。この問題を防ぐには、文字列データタイプの属性を使用してください。ただし、このデータタイプはセグメンテーションの数値比較では利用できません。

デフォルト属性のタイプ

一部のデフォルト属性は、ユーザー更新に有効な特定の値のみを受け付ける場合があります。ガイダンスについては、CSVの構築を参照してください。

末尾のスペースや大文字小文字の違いにより、値が無効として解釈される場合があります。例えば、以下のCSVファイルでは、受け付けられる値がunsubscribed、subscribed、opted_inであるため、最初の行のユーザー（brazetest1）のみがメールとプッシュのステータスを正常に更新されます。

1
2
3

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

「Select CSV File」が機能しない

Select CSV Fileボタンが機能しない理由はいくつかあります。
New Stuff!