オーディエンスのエクスポートの基礎

Google アナリティクス 4 のオーディエンスを使うと、ビジネスの目的に合わせてユーザーをセグメント化できます。オーディエンスを使用すると、共有属性に基づいてサイトまたはアプリケーションのユーザーをグループ化できます。

Google Analytics Data API v1 を使うと、オーディエンスに含まれるユーザーのスナップショットを含むオーディエンスのエクスポートを生成できます。

オーディエンスのエクスポートを作成する

Google Analytics Data API v1 は、非同期の方法でオーディエンスのエクスポートを作成します。まず、ユーザーのオーディエンス エクスポートを作成するには、audienceExports.create メソッドへのリクエストが必要です。次に、audienceExports.query メソッドを使用して、オーディエンス内のユーザーを取得します。

また、audienceExports.get を使用して特定のオーディエンス エクスポートに関する設定メタデータを取得し、audienceExports.list を使用してプロパティのすべてのオーディエンス エクスポートを一覧表示することもできます。

報告エンティティを選択

Data API v1 のすべてのメソッドでは、URL リクエストパス内で Google アナリティクス 4 プロパティ識別子properties/GA4_PROPERTY_ID の形式で指定する必要があります。次に例を示します。

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports

レポートは、指定した Google アナリティクス 4 プロパティで収集された Google アナリティクス イベントデータに基づいて生成されます。

Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントには、properties/GA4_PROPERTY_ID 形式の文字列を想定する property パラメータが用意されています。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。

オーディエンスのエクスポートの作成をリクエストする

オーディエンス エクスポートを作成するには、リクエストで AudienceExport オブジェクトを使用して audienceExports.create メソッドを呼び出します。次のパラメータを指定します。

  • audience フィールドの有効なオーディエンス名(properties/{propertyId}/audiences/{audienceId} 形式)。この値は、Google アナリティクス Admin API v1 の audiences.list メソッドを使って取得できます。audiences.list レスポンスの Audience.name フィールドにオーディエンス名が含まれます。
  • dimensions フィールド内の有効なディメンションのリスト。このメソッドでサポートされるディメンションのリストについては、オーディエンス エクスポート スキーマのドキュメントをご覧ください。オーディエンスのエクスポートには、このフィールドで指定されたディメンションのデータのみが含まれます。

オーディエンスのエクスポート作成リクエストの例:

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

audienceExports.create メソッドのレスポンスでは、name フィールドにオーディエンス エクスポート名(properties/1234567/audienceExports/123 など)が含まれます。この名前を後続のクエリで使用して、オーディエンス エクスポートからユーザーを取得できます。

HTTP レスポンス

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

オーディエンスのエクスポートの準備状況をクエリする

audienceExports.create を呼び出した後に、オーディエンスのエクスポートが生成されるまで数分かかることがあります。オーディエンスのエクスポートの準備状況を取得するには、audienceExports.get メソッドを呼び出します。

audienceExports.create レスポンスで受け取ったオーディエンス エクスポート名(properties/1234567/audienceExports/123 など)を使用して、オーディエンス エクスポートを指定します。

例:

HTTP リクエスト

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

オーディエンスのエクスポートの準備状況は、レスポンスの state フィールドに返されます。オーディエンスのエクスポートの生成が完了すると、状態が CREATING から ACTIVE に変わります。

HTTP レスポンス

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

すべてのオーディエンスのエクスポートの状態を取得するには、audienceExports.list メソッドを呼び出します。

オーディエンスのエクスポートでユーザーを取得する

audienceExports.create メソッドを使用して作成されたオーディエンス エクスポートが生成されたら、audienceExports.query メソッドを呼び出して、オーディエンス エクスポートの名前(properties/1234567/audienceExports/123 など)を指定します。

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

オーディエンスのエクスポートの準備ができると、オーディエンス内のユーザーのリストを含むレスポンスが返されます。

HTTP レスポンス

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}

オーディエンスのエクスポートデータで想定されること

次のセクションでは、オーディエンス エクスポートにおけるユーザー メンバーシップの期待値について説明します。

データの更新頻度

オーディエンス エクスポート データの更新頻度とは、Google アナリティクスがイベントの収集、イベントの処理、オーディエンスのユーザー メンバーシップの更新を行うのに要する時間です。このプロセス全体に 24 時間かかる場合、オーディエンス エクスポート データの更新頻度は 24 時間となります。詳しくは、データの更新頻度をご覧ください。

たとえば、ユーザーが最初の購入を完了し、7 時間後に「購入者」オーディエンスのオーディエンス エクスポートを作成した場合、そのユーザーはまだ「購入者」オーディエンスにエクスポートされていないことがほとんどです。そのユーザーは、最初の購入から 14 ~ 38 時間後に新しいオーディエンスのエクスポートの対象となります。

オーディエンスのエクスポートはスナップショット

オーディエンスのエクスポートは、特定のスナップショットにおけるオーディエンス内のユーザーのリストです。Google 広告リマーケティングの場合、Google アナリティクスはオーディエンス内のユーザーを Google 広告に自動的かつ継続的にエクスポートします。一方、Data API v1 を使って作成したオーディエンスのエクスポートでは、そのオーディエンスの最新のユーザーを表示するために、新しいオーディエンスのエクスポートを作成する必要があります。

オーディエンスのエクスポートは、利用可能な最新のユーザー メンバーシップに基づいて作成されます。ただし、オーディエンスのエクスポートではデータの更新頻度をたとえば 20 時間程度にすることができます。この場合、オーディエンスのエクスポートは現時点での 20 時間前のすべてのイベントに基づいて行われます。

最新のメンバーシップ データは 1 日に 1 回、通常はプロパティのタイムゾーンの昼間に更新されます。つまり、午前 9 時と午前 11 時の同じオーディエンスのオーディエンス エクスポートでは、多くの場合同じデータが返されますが、午後 3 時のオーディエンス エクスポートは、1 日分のデータを含めることで異なる場合があります。

オーディエンスのエクスポートの期限

オーディエンスのエクスポートは 72 時間後に期限切れとなります。新規ユーザーは毎日、ユーザー層を訪問および退出できます。最新のユーザー スナップショットを取得するには、毎日新しいオーディエンスのエクスポートを作成する必要があります。

オーディエンスのエクスポートのユーザー数の上限

オーディエンスまたはプロパティのサイズがユーザーの上限を超えると、オーディエンスのエクスポートではオーディエンスの代表サンプルが返されます。これらの上限はプロパティ タイプ(標準プロパティまたは 360 プロパティ)によって異なり、それぞれのオーディエンス エクスポートで個別に適用されます。戻りユーザーは、リクエストされたオーディエンスに含まれるユーザーです。また、オーディエンスのメンバーである場合もあります。

制限のタイプ 標準プロパティの上限 アナリティクス 360 プロパティの上限
最大リピーター数 200 万回 2 億
最大考慮済みユーザー数 1,000 万 10 億

レポート ID の整合性

レポート用識別子は、レポートでのユーザーの重複除去方法を決定します。オーディエンスのエクスポートは、レポート用識別子の設定に基づいて変更されません。 オーディエンスのエクスポートでは、ユーザーは常に User-ID、次にデバイス ID で識別されます。

つまり、オーディエンス レポートには、オーディエンスのエクスポートで得られた結果よりも多くのユーザー数が表示される可能性があります。たとえば、レポート ID が「デバイスベース」でユーザー ID が収集されている場合、レポートではユーザー ID に基づいてユーザーの重複除去は行われませんが、オーディエンスのエクスポートではユーザー ID に基づいて重複除去が行われます。

また、オーディエンスに関するレポートで、オーディエンスのエクスポートによる結果よりもユーザー数が少なくなる場合があります。たとえば、レポート ID が「混合」の場合、レポートでは Google シグナルに基づいてユーザーの重複が除去されますが、オーディエンスのエクスポートでは重複除去されません。

バックフィルの整合性

Google アナリティクスでオーディエンスを作成して Google 広告のリマーケティングを有効にすると、Google アナリティクスでは、最近追加されたメンバーに基づいて Google 広告の該当オーディエンスがバックフィルされます。ただし、Google アナリティクスのレポートとオーディエンス エクスポートには、バックフィルされたオーディエンス メンバーシップは含まれません。オーディエンスの作成後にユーザーがイベントをロギングすると、レポートとオーディエンスのエクスポートでそのオーディエンスにユーザーが表示されます。

たとえば、あるユーザーが 6 月 20 日に購入イベントを記録し、お客様が 6 月 21 日に「購入者」オーディエンスを作成した場合、新しいオーディエンス エクスポートでそのユーザーが表示される可能性は、6 月 22 日まで待たなければならない可能性があります。ただし、このユーザーがオーディエンス エクスポートに表示されるのは、6 月 21 日にユーザーがなんらかのイベントを記録している場合のみです。