Google アナリティクス 4 のインポート

AmplitudeのGoogle アナリティクス 4連携により、Google アナリティクス 4のデータをAmplitudeプロジェクトに取り込むことができます。

前提条件

GA4 からのインポートを開始するには、いくつかの前提条件を満たしてください。

• BigQuery リンクを設定します。
• GCS バケットを作成します。 Amplitudeは、この目的専用のものを推奨しています。BigQuery のエクスポートオプションが限られているため、取り込みプロセスではデータをAmplitudeに取り込む前に GCS バケットにオフロードする必要があります。
• 取り込みたいバケットとテーブルに対して権限が付与されたサービスアカウントを作成し、サービスアカウントキーを取得します。 サービスアカウントには、次の役割が付与されている必要があります。
  • BigQuery：
    • プロジェクトレベルのBigQueryジョブユーザー。
    • 取り込みたいデータにアクセスするために必要なリソースレベルの BigQuery データビューア。 データが 1 つのテーブルにある場合は、そのテーブル リソース用のサービス アカウント BigQuery Data Viewer を付与してください。 クエリに複数のテーブルまたはデータセットが必要な場合は、クエリ内のすべてのテーブルまたはデータセットに BigQuery Data Viewer を許可してください。
  • Cloud Storage:
    • 取り込みに使用している GCS バケットの Storage Admin。
• 会社のネットワークポリシーによっては、AmplitudeのサーバーがBigQueryインスタンスにアクセスできるようにするために、許可リストに次のIPアドレスを追加する必要がある場合があります。
  • Amplitude米国のIPアドレス:
    • 52.33.3.219
    • 35.162.216.242.
    • 52.27.10.221.
  • Amplitude EU の IP アドレス:
    • 3.124.22.25.
    • 18.157.59.125.
    • 18.192.47.195.

AmplitudeがGA4データをインポートする方法

以下はAmplitudeがGA4データをどのようにインポートするかを段階ごとに説明しています。

1. GA4データをBigQueryにエクスポートします。

   まず、AmplitudeはBigQuery Linkingを通じてGA4データをBigQueryプロジェクトにエクスポートします。 このプロセスにより、GA4からBigQueryへのイベントデータの自動フローが作成されます。

2. BigQueryからGCSバケットにデータをアンロードします。

   BigQuery のエクスポート制限（エクスポートサイズ制限など）に対処するために、Amplitude は BigQuery から指定した GCS バケットにデータをアンロードします。 これにより、Amplitudeへの取り込みに備えてデータの準備が整います。

   • 遅延処理：

     データの完全性を確保するために、AmplitudeはGA4のエクスポートプロセスに起因する遅延を考慮しています：

     • 日次エクスポートの場合は72時間。
     • ストリーミングエクスポートは24時間以内です。

   • キャッチアップインポート：

     バックログがある場合、Amplitudeはキャッチアップ戦略を使用して、1日あたり10テーブルのバッチ処理を行います。 例えば：

     • インポートを2025-01-01のイベントテーブルから開始するように設定した場合、今日の日付が2025-01-24である場合、Amplitudeは次のようにインポートします。
       • 2025-01-01～2025-01-10は、2025-01-24の最初のバッチです。
       • 2025-01-11から2025-01-20までを、2025-01-25の第2バッチでインポートします。
       • 2025-01-21から2025-01-23までを、2025-01-26の第3バッチでインポートします。
       • 2025-01-24 は 2025-01-27 です（毎日のエクスポートに 72 時間遅延が発生するため）。

   アンロード処理中、Amplitudeはデータをシームレスに取得するために必要なフォーマットに変換します。

3. GCS から Amplitude にデータをインポートします。

   GCS バケットにデータが準備された後、Amplitude がお客様に代わってデータをインポートします。

ソースとしてのGA4の追加

GA4をAmplitudeプロジェクトのデータソースとして追加するには、以下の手順に従ってください。

1. Amplitudeで「データ」、「カタログ」をクリックし、「ソース」タブを選択します。

2. データウェアハウス セクションで、Google Analytics 4 をクリックします。

3. サービスアカウントキーを追加し、GCS バケット名を指定します。

4. 資格情報を確認したら、次へをクリックしてテーブルの選択を設定します。以下のオプションに従ってください。

   • テーブルタイプの選択：BigQuery リンクで設定したエクスポートタイプに基づいてテーブルタイプを選択します。
     • Daily：毎日に設定している場合は選択します。
     • ストリーミング：ストリーミング機能を有効に設定した場合に選択します。
     • 両方: 両方を選択した場合は、Daily を選択します。
   • 入力テーブル名: projectId.datasetName.tableName の形式でテーブル名を入力してください。
     • 重要な注意事項：Amplitudeは、提供された最初のテーブルからデータを継続的にインポートします。ただし、GA4のデータエクスポートの遅延により、
       • 毎日のテーブルには 72 時間の遅延があります。
       • ストリーミングテーブルには 24 時間の遅延があります。
     • たとえば、2025-01-01にインポートを開始し、今日の日付が2025-01-05の場合、Amplitudeはまず2025-01-01と2025-01-02のデータをインポートします。翌日（2025-01-06）には、インポートには2025-01-03が含まれます。このプロセスにより、データのインポートが完了することが保証されます。インポートが早すぎるとデータが不完全になる可能性があります。

5. オプションを設定したら、［Next］をクリックします。Amplitudeは事前定義されたSQLクエリを実行して、BigQueryからのデータインポートを検証します。 AmplitudeはGA4データを互換性のあるフォーマットに変換します。 必須フィールドについては、Amplitude HTTP V2 APIのドキュメントを参照してください。

   • SQLの編集：通常、事前定義済みのクエリはすべての必須フィールドを処理しますが、必要に応じて追加フィールドを含めるようにクエリをカスタマイズすることもできます。

6. エラーが発生しなかった場合は、「次へ」をクリックします。 ソース名を入力し、「保存」をクリックします。 AmplitudeがGA4ソースを有効にしたことを確認する通知が表示されます。 [ソース] リストページが読み込まれ、新しく作成された GA4 ソースがリストに表示されます。

セットアッププロセス中に問題が発生したり、質問がある場合は、Amplitudeチームに連絡してサポートを受けてください：サポートにお問い合わせください。

BigQuery SQLのヒント

これらのヒントとベストプラクティスは、BigQueryのSQLクエリをナビゲートするのに役立ちます。このクエリは他のSQLクエリとはいくつかの点で異なります。

プロパティフィールド

プロパティキーと値で構成される「プロパティ」フィールドは、Amplitudeの多くの機能を強化します。 これらのプロパティのフィールドの中で最も一般的なものは event_properties と user_properties です。

Amplitudeがこれらのキーと値のセットを正しく取り込むためには、BigQueryはそれらをJSON文字列ではなく、生のJSONとしてエクスポートする必要があります。BigQueryはJSONを強力にサポートしていませんが、以下では、BigQueryからデータをエクスポートし、エラーなくAmplitudeにインポートする方法について説明します。

プロパティフィールドは、STRUCTタイプの列から取得されます。STRUCT タイプはキーと値の構造を表すフィールドタイプで、BigQuery から生の JSON 形式でエクスポートされます。

ソーステーブルにイベントまたはユーザープロパティが構造体タイプの列に整理されていない場合は、SELECT SQLで作成できます。たとえば、イベントプロパティがすべて独自の列にフラット化されている場合、次のようにして構造体event_propertiesに構成できます。

SELECT STRUCT(
    event_property_column_1 AS event_property_name_1,
    event_property_column_2 AS event_property_name_2
) as event_properties
FROM your_table;

レコードタイプフィールドと繰り返しモードフィールドからイベントまたはユーザープロパティを再構築する

RECORDタイプとREPEATEDモードを持つevent_propertiesまたはuser_propertiesフィールドがある場合は、Amplitudeに取り込む前に有効なフォーマットに変換する必要があります。

この変換を実現するためのアプローチは、次の2つです。

• PARSE_JSON を使用してプロパティを JSON オブジェクトに再構築し、すべての値が適切にフォーマットされていることを確認できます:

PARSE_JSON(CONCAT('{',
    (
      SELECT STRING_AGG(
          CONCAT('"', key, '":"',
            COALESCE(
              NULLIF(CODE_POINTS_TO_STRING(
                ARRAY((
                  SELECT * FROM UNNEST((
                    SELECT TO_CODE_POINTS(CAST(value.string_value AS STRING))
                  )) AS code_points
                  WHERE code_points > 31 AND code_points != 34 AND code_points != 92
                ))
              ), ''),
              NULLIF(CAST(value.int_value AS STRING), ''),
              NULLIF(CAST(value.float_value AS STRING), ''),
              NULLIF(CAST(value.double_value AS STRING), '')
            ),
            '"'
          )
      ) FROM UNNEST(event_properties)
    ),
    '}'
  )) AS event_properties

• あるいは、個々のキーと値のペアを直接抽出することもできます。

(SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'key1') AS key1,
(SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'key2') AS key2

イベントプロパティを変換した後、Amplitudeが取り込むためのSTRUCTとしてフォーマットします：

STRUCT
(
  action AS action,
  field AS field
) AS event_properties

JSON文字列フィールドからのプロパティ

イベントまたはユーザープロパティを文字列フィールドにJSON形式でフォーマットしている場合でも、選択SQL内のプロパティフィールドをSTRUCTとして再構築する必要があります。BigQuery は、コンテンツが JSON であっても、文字列フィールドを String としてエクスポートします。 Amplitudeのイベント検証はこれらを拒否します。

ただし、JSON文字列フィールドから値を抽出し、プロパティSTRUCTで使用することはできます。JSON_EXTRACT_SCALAR関数を使用して、次のように文字列内の値にアクセスします。テーブルのEVENT_PROPERTIES列に次のような JSON 文字列が含まれている場合:

"{\"record count\":\"50\",\"region\":\"eu-central-1\"}" これは BigQuery UI に {"record count":"50","region":"eu-central-1"}) として表示されます。この場合、次の SQL を使用して JSON 文字列から値を抽出できます。

SELECT STRUCT(
   JSON_EXTRACT_SCALAR(EVENT_PROPERTIES, "$.record count") AS record_count,
   JSON_EXTRACT_SCALAR(EVENT_PROPERTIES, "$.region") AS region
) as event_properties
FROM your_table;