Google アナリティクス 4 のオーディエンスを使用すると、ビジネスの目的に合わせてユーザーをセグメント化できます。オーディエンスを使用すると、共通の属性に基づいてサイトまたはアプリのユーザーをグループ化できます。
Google Analytics Data API v1 を使って、オーディエンスに含まれるユーザーのスナップショットを含むオーディエンスのエクスポートを生成できます。
オーディエンスのエクスポートを作成する
Google Analytics Data API v1 は、非同期のアプローチでオーディエンスのエクスポートを作成します。まず、ユーザーのオーディエンス エクスポートを作成するには、audienceExports.create
メソッドへのリクエストが必要です。次に、audienceExports.query
メソッドを使用して、オーディエンスに含まれるユーザーを取得します。
また、audienceExports.get
を使用して特定のオーディエンスのエクスポートに関する設定メタデータを取得し、audienceExports.list
を使用してプロパティのすべてのオーディエンスのエクスポートを一覧表示できます。
報告エンティティを選択
Data API v1 のすべてのメソッドで、URL リクエストパス内に properties/GA4_PROPERTY_ID
の形式で Google アナリティクス 4 プロパティ識別子を指定する必要があります。次に例を示します。
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 Analytics 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 時のオーディエンスのエクスポートでは、追加日のデータを含めると異なる場合があります。
オーディエンスのエクスポートの有効期限
オーディエンスのエクスポートは 72 時間後に期限切れとなります。毎日、新規ユーザーがオーディエンスに参加したり、そこから離脱したりする可能性があります。最新のユーザー スナップショットを取得するには、毎日新しいオーディエンスのエクスポートを作成する必要があります。
オーディエンスのエクスポートのユーザー数の上限
オーディエンスまたはプロパティのサイズがユーザーの上限を超えると、オーディエンスのエクスポートではオーディエンスの代表サンプルが返されます。これらの制限はプロパティ タイプ(標準プロパティまたは 360 プロパティ)によって異なり、各オーディエンスのエクスポートで個別に適用されます。リピーターとは、リクエストされたオーディエンスに含まれるユーザーを指します。ユーザーは、オーディエンスのメンバーになる場合もあれば、そうでない場合もあります。
制限のタイプ | 標準プロパティの上限 | アナリティクス 360 プロパティに関する制限事項 |
---|---|---|
最大リピーター数 | 200 万回 | 2 億 |
最大検討ユーザー数 | 1,000 万 | 10 億 |
レポート用識別子の整合性
レポート用識別子は、レポートでユーザーの重複をどのように除去するかを決定します。オーディエンスのエクスポートは、レポート用識別子の設定に基づいて変更されません。 オーディエンスのエクスポートでは、常に User-ID、デバイス ID の順にユーザーを識別します。
つまり、オーディエンスのレポートには、オーディエンスのエクスポートで得られた数よりも多くのユーザーが表示される可能性があります。たとえば、レポート ID が「デバイスベース」でユーザー ID が収集されている場合、レポートではユーザー ID に基づいてユーザーの重複が除去されませんが、オーディエンスのエクスポートではユーザー ID に基づいて重複が除去されます。
バックフィルの整合性
Google アナリティクスでオーディエンスを作成して Google 広告のリマーケティングを有効にすると、Google アナリティクスでは、最近追加されたメンバーに基づいて Google 広告の該当オーディエンスがバックフィルされます。ただし、Google アナリティクスのレポートとオーディエンスのエクスポートには、バックフィルされたオーディエンスのメンバーは含まれません。オーディエンスの作成後にユーザーがイベントをロギングすると、レポートとオーディエンスのエクスポートでそのオーディエンスにユーザーが表示されます。
たとえば、ユーザーが 6 月 20 日に購入イベントを記録し、お客様が 6 月 21 日に「購入者」オーディエンスを作成した場合、新しいオーディエンスのエクスポートでそのユーザーが表示されるようになるには、6 月 22 日まで待つ必要があります。ただし、このユーザーがオーディエンス エクスポートの対象になるのは、6 月 21 日にユーザーがなんらかのイベントを記録している場合のみです。