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 saat daftar dibuat.

Membuat daftar audiens baru setiap hari

Diperlukan waktu yang bervariasi untuk memproses data audiens satu hari dan memperbarui langganan. 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 lain, daftar audiens akan berbeda dan berisi perubahan keanggotaan hari tambahan.

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 langganan 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 saat data hari tambahan tersedia. Hal ini menghilangkan tebakan saat memutuskan kapan harus membuat Daftar Audiens baru. Sebagai gantinya, Anda dapat melakukan polling Daftar Audiens Berulang dengan biaya murah sepanjang hari untuk melihat apakah data tambahan tersedia.

Melakukan polling Daftar Audiens berulang secara berkala selama 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 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 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. File 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 cara menggunakan Webhook di Google Analytics Data API v1.

Mengambil pengguna dalam ekspor audiens

Untuk mengambil pengguna di 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
}