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

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

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

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

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

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

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

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

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

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

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

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

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

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

درخواست اچ‌تی‌تی‌پی

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

مثالی در اینجا ارائه شده است:

درخواست اچ‌تی‌تی‌پی

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 ، می‌توانید وقتی فهرست مخاطبان دردسترس قرار می‌گیرد، اعلان‌های Webhook را به‌صورت ناهمگام دریافت کنید.

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

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

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

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

درخواست اچ‌تی‌تی‌پی

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
}