لیست مخاطبان تکراری

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

فهرست‌های مخاطبان دوره‌ای، روزانه و با تغییر عضویت مخاطبان، فهرست مخاطبان را تولید می‌کنند تا اطمینان حاصل شود که با جدیدترین داده‌ها کار می‌کنید.

فهرست‌های مخاطبان منظم (غیرتکراری)، فهرست‌های ثابتی از کاربران حاضر در فهرست مخاطبان در زمان تولید فهرست هستند.

روزانه یک لیست مخاطب جدید ایجاد کنید

پردازش داده‌های مخاطبان یک روز و به‌روزرسانی عضویت، زمان متغیری طول می‌کشد. هیچ راهی برای اطمینان از به‌روزرسانی داده‌های فهرست مخاطبان در ۲۴ ساعت وجود ندارد.

برای مثال، حتی اگر هر روز در یک ساعت مشخص درخواست فهرست مخاطبان را بدهید، در برخی روزها فهرست مخاطبان مشابه روز قبل خواهد بود و در روزهای دیگر، فهرست مخاطبان متفاوت خواهد بود و شامل یک روز اضافی از تغییرات عضویت می‌شود.

فهرست‌های مخاطبان بر اساس داده‌های رویداد یک روز قبل از آخرین تغییرات عضویت هستند. اگر فهرست مخاطبان را قبل از به‌روزرسانی‌های روزانه عضویت ایجاد کنید، از داده‌های دو روز قبل استفاده خواهد شد. اگر فهرست مخاطبان را بعد از به‌روزرسانی‌های روزانه عضویت ایجاد کنید، از داده‌های دیروز استفاده خواهد شد.

به صورت دوره‌ای از لیست مخاطبان تکراری نظرسنجی کنید

فهرست‌های مخاطبان تکرارشونده فقط زمانی فهرست‌های مخاطبان را تولید می‌کنند که داده‌های یک روز اضافی در دسترس باشد. این کار حدس و گمان برای تصمیم‌گیری در مورد زمان ایجاد فهرست‌های مخاطبان جدید را از بین می‌برد. در عوض، می‌توانید در طول روز به راحتی فهرست مخاطبان تکرارشونده را نظرسنجی کنید تا ببینید آیا داده‌های اضافی در دسترس است یا خیر.

یک لیست مخاطبان تکراری ایجاد کنید

برای ایجاد یک لیست مخاطبان تکرارشونده، متد recurringAudienceLists.create را با استفاده از شیء RecurringAudienceList در یک درخواست فراخوانی کنید. پارامترهای زیر مورد نیاز هستند:

• یک نام مخاطب معتبر در فیلد audience ، که به صورت properties/{propertyId}/audiences/{audienceId} قالب‌بندی شده است. می‌توانید از متد audiences.list از Google Analytics Admin API v1 برای به دست آوردن این مقدار استفاده کنید. فیلد Audience.name از پاسخ audiences.list حاوی نام مخاطب است.
• فهرست معتبری از ابعاد در فیلد dimensions . فهرست ابعاد پشتیبانی شده توسط این روش را می‌توان در مستندات Audience Export Schema یافت. فقط داده‌های مربوط به ابعاد ذکر شده در این فیلد در فهرست مخاطبان گنجانده می‌شوند.

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

درخواست HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

پاسخ متد recurringAudienceLists.create شامل نامی در فیلد name است (مانند properties/1234567/recurringAudienceLists/123 )، که می‌تواند در پرس‌وجوهای بعدی برای بازیابی فراداده‌های پیکربندی برای این فهرست مخاطبان تکرارشونده استفاده شود. همچنین، فراداده‌های پیکربندی شامل نام‌های منابع برای نمونه‌های فهرست مخاطبان ایجاد شده برای این فهرست مخاطبان تکرارشونده است.

پاسخ HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

فراداده پیکربندی نظرسنجی

از متد recurringAudienceLists.get برای بازیابی فراداده‌های پیکربندی مربوط به یک لیست مخاطبان تکرارشونده خاص استفاده کنید. فراداده‌های پیکربندی شامل نام منابع برای نمونه‌های لیست مخاطبان ایجاد شده برای این لیست مخاطبان تکرارشونده است.

در اینجا یک مثال آورده شده است:

درخواست HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

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

پاسخ HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

شما می‌توانید recurringAudienceLists.list برای فهرست کردن تمام فهرست‌های مخاطبان تکرارشونده برای یک ویژگی استفاده کنید.

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

به جای اینکه به صورت دوره‌ای با استفاده از متد recurringAudienceLists.get ، فراداده‌های پیکربندی مربوط به یک لیست خاص از مخاطبان تکراری را بررسی کنید، می‌توانید به صورت غیرهمزمان اعلان‌های Webhook را هنگام در دسترس قرار گرفتن لیست مخاطبان دریافت کنید.

برای پیکربندی اعلان‌های Webhook، هنگام ایجاد لیست مخاطبان تکراری جدید، فیلد webhookNotification را مشخص کنید.

برای اطلاعات بیشتر در مورد استفاده از وب‌هوک‌ها در Google Analytics Data API نسخه ۱، راهنمای Async audience lists with webhooks دنبال کنید.

بازیابی کاربران در خروجی مخاطبان

برای بازیابی کاربران در یک خروجی Audience، متد audienceExports.query را فراخوانی کنید و نام خروجی Audience را که از فراداده‌های پیکربندی ارائه شده توسط recurringAudienceLists.get یا recurringAudienceLists.list بازیابی شده است، مشخص کنید.

درخواست HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

اگر خروجی مخاطب آماده باشد، پاسخی حاوی لیست کاربران یک مخاطب بازگردانده می‌شود:

پاسخ HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}