আপনার দর্শক তালিকার জন্য ওয়েবহুক বিজ্ঞপ্তি পান

এই নির্দেশিকায় ব্যাখ্যা করা হয়েছে কীভাবে ওয়েবহুক ব্যবহার করে আপনার অডিয়েন্স এক্সপোর্ট অনুরোধগুলির অবস্থা সম্পর্কে অ্যাসিঙ্ক্রোনাস নোটিফিকেশন পাওয়া যায়। এই বৈশিষ্ট্যটি শুধুমাত্র ডেটা এপিআই-এর v1alpha সংস্করণে উপলব্ধ।

ওয়েবহুক নোটিফিকেশন হলো গুগল অ্যানালিটিক্স ডেটা এপিআই- এর একটি উন্নত বৈশিষ্ট্য। অডিয়েন্স এক্সপোর্ট বৈশিষ্ট্যটির পরিচিতির জন্য, ‘ক্রিয়েট অ্যান অডিয়েন্স এক্সপোর্ট’ দেখুন।

ওয়েবহুক ছাড়া, কোনো অনুরোধ কখন সম্পন্ন হয়েছে তা জানার জন্য আপনাকে পর্যায়ক্রমে এপিআই পোল করতে হবে।

ক্লাউড রান ব্যবহার করে একটি নমুনা ওয়েবহুক অ্যাপ্লিকেশন তৈরি করুন

আপনি "কুইকস্টার্ট: ক্লাউড রানে একটি নমুনা পরিষেবা স্থাপন করুন" টিউটোরিয়ালটি অনুসরণ করে গুগল ক্লাউড ব্যবহার করে একটি নমুনা ওয়েবহুক অ্যাপ্লিকেশন তৈরি করতে পারেন।

স্যাম্পল সার্ভিসটি যাতে 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 রিটার্ন করে।

একবার আপনি ক্লাউড রান কুইকস্টার্ট টিউটোরিয়ালটি শেষ করে gcloud run deploy কমান্ড ব্যবহার করে ওয়েবহুক অ্যাপ্লিকেশনটি ডিপ্লয় করে ফেললে, আপনার সার্ভিসটি যেখানে ডিপ্লয় করা হয়েছে সেই URL-টি সংরক্ষণ করুন।

সার্ভিস ইউআরএলটি কনসোলে প্রদর্শিত হয়, উদাহরণস্বরূপ:

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

এটি হলো সার্ভার নোটিফিকেশন ইউআরআই , যেখানে আপনার অ্যাপ্লিকেশন গুগল অ্যানালিটিক্স থেকে ওয়েবহুক নোটিফিকেশন শোনে।

একটি দর্শক তালিকা তৈরি করুন এবং ওয়েবহুক বিজ্ঞপ্তি চালু করুন।

ওয়েবহুক নোটিফিকেশন অনুরোধ করতে, webhookNotification অবজেক্টে নিম্নলিখিত মানগুলি উল্লেখ করুন:

  • সার্ভার নোটিফিকেশন ইউআরআই, যাতে সেই ওয়েব ঠিকানাটি থাকে যা ওয়েবহুক নোটিফিকেশন গ্রহণ করবে।

  • (ঐচ্ছিক) মেসেজ স্পুফিং প্রতিরোধ করার জন্য একটি যথেচ্ছ স্ট্রিং channelToken । ওয়েবহুক POST রিকোয়েস্টের X-Goog-Channel-Token HTTP হেডারে channelToken উল্লেখ করুন।

ওয়েবহুক ব্যবহার করে একটি নমুনা অনুরোধ নিচে দেওয়া হলো:

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 মেথডটি কল করার পর ওয়েবহুকগুলো পরীক্ষা করার জন্য, আপনি আপনার নমুনা ক্লাউড রান ওয়েবহুক অ্যাপ্লিকেশনের লগগুলো খতিয়ে দেখতে পারেন এবং গুগল অ্যানালিটিক্স দ্বারা প্রেরিত প্রতিটি নোটিফিকেশনের JSON বডি দেখতে পারেন।