Dapatkan notifikasi webhook untuk daftar audiens Anda

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

Notifikasi webhook adalah fitur lanjutan dari Data API Google Analytics. Untuk 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 memulai cepat 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 keberhasilan operasi.

Setelah Anda menyelesaikan tutorial memulai cepat 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 objek webhookNotification:

  • 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 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 dikirimkan 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 akan segera dikirim, 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 daftar audiens selesai dibuat. 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 dikueri menggunakan metode audienceLists.query.

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