دریافت اعلان‌های وب‌قلاب برای فهرست‌های مخاطبان

این راهنما توضیح می‌دهد که چگونه از وب‌قلاب‌ها برای دریافت اعلان‌های ناهمزمان برای وضعیت درخواست‌های صادر کردن مخاطب استفاده کنید. این ویژگی فقط در نسخه v1alpha «میانای برنامه‌سازی کاربردی داده» دردسترس است.

اعلان‌های وب‌قلاب یک ویژگی پیشرفته از Data API در Google Analytics است. برای آشنایی با ویژگی صادر کردن مخاطب، ایجاد صادر کردن مخاطب را ببینید.

بدون وب‌قلاب، باید به‌طور دوره‌ای از API نظرسنجی کنید تا مشخص شود درخواست چه زمانی تکمیل شده است.

ایجاد کردن برنامه وب‌قلاب نمونه بااستفاده از Cloud Run

با دنبال کردن آموزش شروع سریع: استقرار سرویس نمونه در Cloud Run می‌توانید برنامه وب‌قلاب نمونه‌ای بااستفاده از Google Cloud بسازید.

برای اینکه سرویس نمونه به درخواست‌های اعلان وب‌قلاب POST گوش دهد، فایل index.js را از آموزش شروع سریع با کد زیر جایگزین کنید:

  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}`);
  });

برای هر اعلان وب‌قلاب ورودی که به‌عنوان درخواست POST ارسال می‌شود، این کد بدنه JSON اعلان وب‌قلاب و مقدار کد کانال را چاپ می‌کند و کد HTTP 200 را برای نشان دادن عملکرد موفق برمی‌گرداند.

پس‌از اینکه به انتهای آموزش گام‌به‌گام Cloud Run رسیدید و برنامه وب‌قلاب را بااستفاده از دستور gcloud run deploy مستقر کردید، نشانی وب محل استقرار سرویس خود را ذخیره کنید.

نشانی وب سرویس در کنسول نمایش داده می‌شود، برای مثال:

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

این نشانی وب اعلان سرور است که در آن برنامه شما به اعلان‌های وب‌قلاب از Google Analytics گوش می‌دهد.

ایجاد فهرست مخاطبان و روشن کردن اعلان‌های وب‌قلاب

برای درخواست اعلان‌های وب‌قلاب، مقادیر زیر را در webhookNotification object مشخص کنید:

  • شناسه منبع یکنواخت اعلان سرور حاوی نشانی وبی که اعلان‌های وب‌قلاب را دریافت خواهد کرد.

  • (اختیاری) رشته‌ای اختیاری channelToken برای محافظت دربرابر جعل پیام. channelToken را در سرصفحه X-Goog-Channel-Token درخواست HTTP وب‌قلاب POST مشخص کنید.

در اینجا یک درخواست نمونه بااستفاده از وب‌قلاب‌ها آورده شده است:

درخواست 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"
    }
  ]
}

پاسخ روش audienceLists.create شامل webhookNotification است که تأیید می‌کند وب‌قلاب مشخص‌شده با موفقیت در کمتر از ۵ ثانیه پاسخ داده است.

در اینجا یک پاسخ نمونه آورده شده است:

پاسخ 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"
    }
  }
}

اگر وب‌قلاب نتواند پاسخ دهد، یا اگر نشانی وب سرویس نادرستی ارائه دهید، به‌جای آن پیام خطا برگردانده می‌شود.

در اینجا نمونه‌ای از خطایی که ممکن است دریافت کنید آورده شده است:

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

پردازش اعلان‌های وب‌قلاب

درخواست POST به سرویس وب‌قلاب حاوی هم نسخه JSON از منبع عملیات طولانی‌مدت در بدنه و هم فیلد sentTimestamp است. مُهر زمان ارسال، زمان دوره یونیکس را در میکروثانیه مشخص می‌کند که درخواست ارسال شده است. می‌توانید از این مهر زمان برای شناسایی اعلان‌های بازپخش‌شده استفاده کنید.

درطول ایجاد فهرست مخاطبان، یک یا دو درخواست POST به وب‌قلاب ارسال می‌شود:

  1. اولین درخواست POST بلافاصله ارسال می‌شود و فهرست مخاطب تازه ایجادشده را در وضعیت CREATING آن نشان می‌دهد. اگر اولین درخواست به وب‌قلاب ناموفق باشد، عملکرد audienceLists.create خطا و جزئیات خطای وب‌قلاب را برمی‌گرداند.
  2. درخواست POST دوم پس‌از تکمیل فهرست مخاطبان ارسال می‌شود. وقتی فهرست مخاطب به وضعیت ACTIVE یا FAILED برسد، ساخت کامل می‌شود.

در اینجا نمونه‌ای از اولین اعلان برای فهرست مخاطبان در حالت 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"
      }
  }

در اینجا نمونه‌ای از اعلان دوم برای فهرست مخاطبان در حالت 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"
      }
  }

اعلان دوم تأیید می‌کند که فهرست مخاطبان ایجاد شده است و آماده است تا بااستفاده از روش audienceLists.query پرسش شود.

برای آزمایش وب‌قلاب‌ها پس‌از فراخوانی روش audienceLists.create، می‌توانید گزارش‌های برنامه وب‌قلاب Cloud Run نمونه‌تان را بازرسی کنید و بدنه JSON هر اعلان ارسالی از Google Analytics را ببینید.