Dapatkan notifikasi webhook untuk daftar audiens Anda

Panduan ini menjelaskan cara menggunakan webhook untuk menerima notifikasi asinkron terkait status permintaan ekspor audiens Anda. Fitur ini hanya tersedia di Data API versi v1alpha.

Notifikasi webhook adalah fitur lanjutan dari Google Analytics Data API. Untuk mengetahui pengantar tentang fitur ekspor audiens, lihat membuat ekspor audiens.

Tanpa webhook, Anda harus melakukan polling API secara berkala untuk menentukan kapan permintaan selesai.

Membuat aplikasi webhook contoh menggunakan Cloud Run

Anda dapat membuat aplikasi webhook contoh menggunakan Google Cloud dengan mengikuti tutorial Panduan memulai: Men-deploy layanan contoh ke Cloud Run.

Agar layanan contoh dapat memproses permintaan notifikasi webhook POST, ganti file index.js dari tutorial panduan memulai dengan kode berikut:

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

Untuk setiap notifikasi webhook masuk yang dikirim sebagai permintaan POST, kode ini akan mencetak isi JSON notifikasi webhook dan nilai token saluran, serta menampilkan kode HTTP 200 untuk menunjukkan operasi yang berhasil.

Setelah Anda mencapai akhir tutorial panduan memulai Cloud Run dan men-deploy aplikasi webhook menggunakan perintah gcloud run deploy, simpan URL tempat layanan Anda di-deploy.

URL layanan ditampilkan di konsol, misalnya:

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

Ini adalah URI notifikasi server tempat aplikasi Anda memproses notifikasi webhook dari Google Analytics.

Membuat daftar audiens dan mengaktifkan notifikasi webhook

Untuk meminta notifikasi webhook, tentukan nilai berikut dalam webhookNotification objek:

  • URI notifikasi server yang berisi alamat web yang akan menerima notifikasi webhook.

  • (Opsional) String arbitrer channelToken untuk melindungi pesan agar tidak dipalsukan. Tentukan channelToken di header HTTP X-Goog-Channel-Token dari permintaan POST webhook.

Berikut adalah contoh permintaan menggunakan webhook:

Permintaan HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Respons dari metode audienceLists.create berisi webhookNotification, yang mengonfirmasi bahwa webhook yang ditentukan berhasil merespons dalam waktu kurang dari 5 detik.

Berikut adalah contoh respons:

Respons HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

Jika webhook gagal merespons, atau jika Anda memberikan URL layanan yang salah, pesan error akan ditampilkan.

Berikut adalah contoh error yang mungkin Anda terima:

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

Memproses notifikasi webhook

Permintaan POST ke layanan webhook berisi versi JSON dari resource operasi yang berjalan lama di isi, dan kolom sentTimestamp. Stempel waktu yang dikirim menentukan waktu epoch Unix dalam mikrodetik saat permintaan dikirim. Anda dapat menggunakan stempel waktu ini untuk mengidentifikasi notifikasi yang diputar ulang.

Satu atau dua permintaan POST dikirim ke webhook selama pembuatan daftar audiens:

  1. Permintaan POST pertama dikirim segera, yang menampilkan daftar audiens yang baru dibuat dalam status CREATING. Jika permintaan pertama ke webhook gagal, operasi audienceLists.create akan menampilkan error dan detail kegagalan webhook.
  2. Permintaan POST kedua dikirim setelah pembuatan daftar audiens selesai. Pembuatan selesai saat daftar audiens mencapai status ACTIVE atau FAILED.

Berikut adalah contoh notifikasi pertama untuk daftar audiens, dalam status CREATING:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

Berikut adalah contoh notifikasi kedua untuk daftar audiens, dalam status ACTIVE:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

Notifikasi kedua mengonfirmasi bahwa daftar audiens telah dibuat dan siap untuk dikueri menggunakan metode audienceLists.query.

Untuk menguji webhook setelah memanggil metode audienceLists.create, Anda dapat memeriksa log aplikasi webhook Cloud Run contoh, dan melihat isi JSON dari setiap notifikasi yang dikirim oleh Google Analytics.