Daftar audiens berulang

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

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

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

Membuat daftar audiens baru setiap hari

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

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

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, audiens akan menggunakan data dari dua hari sebelumnya. Jika Anda membuat daftar audiens setelah pembaruan keanggotaan harian dilakukan, daftar audiens akan menggunakan data dari kemarin.

Buat polling secara berkala atas daftar audiens yang berulang

Daftar Audiens Berulang hanya menghasilkan Daftar Audiens jika data hari tambahan tersedia. Dengan cara ini, Anda tidak perlu lagi mengira-ngira dalam menentukan kapan harus membuat Daftar Audiens baru. Sebagai gantinya, Anda dapat melakukan polling dengan murah di Daftar Audiens Berulang sepanjang hari untuk melihat apakah data tambahan tersedia.

Melakukan polling secara berkala pada Daftar Audiens berulang dalam sehari

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, dengan format properties/{propertyId}/audiences/{audienceId}. Anda dapat menggunakan metode audiences.list di 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 di 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 dalam 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 dokumentasi WebhookNotification untuk mendapatkan informasi lebih lanjut 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
}