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

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

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

فهرست‌های مخاطبان معمولی (غیرتکرارشونده) فهرست‌های ایستا از کاربران در مخاطب در زمان تولید فهرست هستند.

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

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

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

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

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

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

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

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

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

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

درخواست 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 برای فهرست کردن همه فهرست‌های مخاطبان تکرارشونده برای یک دارایی استفاده کنید.

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

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

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

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

بازیابی کاربران در صادر کردن مخاطب

برای بازیابی کاربران در «صادر کردن مخاطب»، audienceExports.query روش را فراخوانی کنید و نام «صادر کردن مخاطب» را که از فراداده پیکربندی ارائه‌شده توسط 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
}