Daftar audiens berulang

Dokumen ini menjelaskan daftar audiens berulang, yang merupakan fitur lanjutan dari Google Analytics Data API v1. Untuk mengetahui pengantar tentang fitur ekspor daftar audiens, lihat panduan dasar ekspor audiens.

Daftar audiens berulang menghasilkan daftar audiens setiap hari saat keanggotaan audiens berubah, untuk memastikan Anda menggunakan data terbaru.

Daftar audiens reguler (tidak berulang) adalah daftar statis pengguna dalam audiens pada saat daftar dibuat.

Membuat daftar audiens baru setiap hari

Diperlukan waktu yang bervariasi untuk memproses data audiens satu hari dan memperbarui keanggotaan. Tidak ada cara untuk memastikan bahwa data daftar audiens diperbarui dalam waktu 24 jam.

Misalnya, meskipun Anda meminta daftar audiens pada waktu yang sama setiap hari, pada beberapa hari daftar audiens akan sama dengan hari sebelumnya, dan pada hari lainnya, daftar audiens akan berbeda dan berisi perubahan keanggotaan tambahan satu hari.

Membuat Daftar Audiens baru setiap hari

Daftar audiens didasarkan pada data peristiwa dari satu hari sebelum perubahan keanggotaan terbaru. Jika Anda membuat daftar audiens sebelum pembaruan keanggotaan harian terjadi, daftar tersebut akan menggunakan data dari dua hari sebelumnya. Jika Anda membuat daftar audiens setelah pembaruan keanggotaan harian terjadi, daftar tersebut akan menggunakan data dari kemarin.

Melakukan polling daftar audiens berulang secara berkala

Daftar Audiens Berulang hanya menghasilkan Daftar Audiens jika data tambahan satu hari tersedia. Hal ini menghilangkan perkiraan saat memutuskan kapan harus membuat Daftar Audiens baru. Sebagai gantinya, Anda dapat melakukan polling Daftar Audiens Berulang secara murah sepanjang hari untuk melihat apakah data tambahan tersedia.

Membuat polling Daftar Audiens berulang secara berkala sepanjang hari

Membuat Daftar Audiens Berulang

Untuk membuat daftar audiens berulang, panggil metode recurringAudienceLists.create menggunakan objek RecurringAudienceList dalam permintaan. Parameter berikut diperlukan:

  • Nama audiens yang valid di kolom audience, yang diformat sebagai properties/{propertyId}/audiences/{audienceId}. Anda dapat menggunakan metode audiences.list Google Analytics Admin API v1 untuk mendapatkan nilai ini. Kolom Audience.name dari respons audiences.list berisi nama audiens.
  • Daftar dimensi yang valid di kolom dimensions. Daftar dimensi yang didukung oleh metode ini dapat ditemukan dalam dokumentasi Skema Ekspor Audiens. Hanya data untuk dimensi yang disebutkan di kolom ini yang disertakan dalam Daftar Audiens.

Berikut adalah contoh permintaan pembuatan daftar audiens berulang:

Permintaan HTTP

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

Respons dari metode recurringAudienceLists.create berisi nama di kolom name (seperti properties/1234567/recurringAudienceLists/123), yang dapat digunakan dalam kueri berikutnya untuk mengambil metadata konfigurasi untuk daftar audiens berulang ini. Selain itu, metadata konfigurasi berisi nama resource untuk instance daftar audiens yang dibuat untuk daftar audiens berulang ini.

Respons HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Metadata konfigurasi polling

Gunakan recurringAudienceLists.get metode untuk mengambil metadata konfigurasi tentang daftar audiens berulang tertentu. Metadata konfigurasi berisi nama resource untuk instance daftar audiens yang dibuat untuk daftar audiens berulang ini.

Berikut contohnya:

Permintaan HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

Instance RecurringAudienceList ditampilkan sebagai respons. Instance ini berisi metadata konfigurasi, yang mencakup nama resource untuk instance daftar audiens yang dibuat untuk daftar audiens berulang ini.

Respons HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Anda dapat menggunakan recurringAudienceLists.list untuk mencantumkan semua daftar audiens berulang untuk properti.

Menggunakan Webhook untuk menerima notifikasi asinkron tentang daftar audiens baru

Daripada melakukan polling metadata konfigurasi secara berkala tentang daftar audiens berulang tertentu menggunakan metode recurringAudienceLists.get, Anda dapat menerima notifikasi Webhook secara asinkron saat daftar audiens tersedia.

Untuk mengonfigurasi notifikasi Webhook, tentukan kolom webhookNotification saat membuat daftar audiens berulang baru.

Ikuti panduan Async audience lists with webhooks untuk mengetahui informasi selengkapnya tentang penggunaan Webhook di Google Analytics Data API v1.

Mengambil pengguna dalam ekspor audiens

Untuk mengambil pengguna dalam Ekspor Audiens, panggil audienceExports.query metode dan tentukan nama Ekspor Audiens yang diambil dari metadata konfigurasi yang disediakan oleh recurringAudienceLists.get atau recurringAudienceLists.list.

Permintaan HTTP

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

Jika Ekspor Audiens siap, respons yang berisi daftar pengguna dalam audiens akan ditampilkan:

Respons 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
}