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

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

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

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

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

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

برای اینکه سرویس نمونه به درخواست های اطلاع رسانی POST webhook گوش دهد، فایل 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 رسیدید و برنامه webhook را با استفاده از دستور gcloud run deploy اجرا کردید، آدرس اینترنتی را که سرویس شما در آن مستقر است ذخیره کنید.

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

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

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

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

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

  • URI اعلان سرور حاوی آدرس وب است که اعلان‌های هوک را دریافت می‌کند.

  • (اختیاری) یک channelToken رشته دلخواه برای محافظت در برابر جعلی شدن پیام. channelToken در هدر HTTP X-Goog-Channel-Token درخواست webhook 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 است که تأیید می کند که وب هوک مشخص شده با موفقیت در کمتر از 5 ثانیه پاسخ داده است.

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

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

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

در اینجا یک مثال خطا وجود دارد که ممکن است دریافت کنید:

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

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

درخواست POST به یک سرویس webhook شامل یک نسخه 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 را ببینید.