Daftar audiens berulang

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

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

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

Membuat daftar audiens baru setiap hari

Pemrosesan data audiens satu hari dan pembaruan keanggotaan memerlukan waktu yang bervariasi. Tidak ada cara untuk memastikan bahwa data daftar audiens diperbarui dalam 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 hari sebelumnya.

Secara berkala melakukan polling pada daftar audiens berulang

Daftar Audiens Berulang hanya menghasilkan Daftar Audiens jika data tambahan tersedia. Hal ini menghilangkan tebakan dalam memutuskan kapan harus membuat Daftar Audiens baru. Sebagai gantinya, Anda dapat melakukan polling Daftar Audiens Berulang dengan biaya murah sepanjang hari untuk melihat apakah ada data tambahan yang tersedia.

Meminta 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, diformat sebagai properties/{propertyId}/audiences/{audienceId}. Anda dapat menggunakan metode audiences.list Google Analytics Admin API v1 untuk mendapatkan nilai ini. Kolom Audience.name 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 dalam 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 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 metode recurringAudienceLists.get 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. Objek 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 metode audienceExports.query 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 sudah 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
}