قوائم المستخدِمين المتكرّرة

يصف هذا المستند قوائم شرائح الجمهور المتكرّرة، وهي ميزة متقدّمة من الإصدار 1 من Google Analytics Data API. للحصول على مقدّمة عن ميزة تصدير قائمة الجمهور، راجِع دليل أساسيات تصدير شرائح الجمهور.

تُنشئ قوائم المستخدمين المتكرّرة قوائم مستخدمين يوميًا مع تغيُّر العضويات في شرائح الجمهور، لضمان استخدام أحدث البيانات.

قوائم المستخدمين العادية (غير المتكرّرة) هي قوائم ثابتة للمستخدمين في شريحة الجمهور في وقت إنشاء القائمة.

إنشاء قائمة جمهور جديدة يوميًا

تستغرق معالجة بيانات الجمهور ليوم واحد وتعديل الاشتراك مدةً متغيرة. لا تتوفّر طريقة للتأكّد من تعديل بيانات قائمة الجمهور في 24 ساعة.

على سبيل المثال، حتى إذا طلبت قائمة جمهور في الوقت نفسه كل يوم، ستكون قائمة الجمهور في بعض الأيام مماثلة للقائمة في اليوم السابق، وفي الأيام الأخرى، ستكون قائمة الجمهور مختلفة و تحتوي على يوم إضافي من التغييرات في العضوية.

تستند قوائم الجمهور إلى بيانات الأحداث من يوم واحد قبل آخر تغييرات في العضوية. إذا أنشأت قائمة جمهور قبل حدوث تعديلات الاشتراكات اليومية، ستستخدِم القائمة البيانات من اليومَين السابقَين. إذا أنشأت قائمة مستخدمين بعد إجراء تعديلات يومية على العضوية، ستستخدم القائمة بيانات الأمس.

إجراء استطلاع دوري لقائمة مستخدمين متكرّرة

لا تنشئ "قوائم المستخدمين المتكرّرة" "قوائم مستخدمين" إلا عندما تتوفّر بيانات يوم إضافي. ويزيل هذا الإجراء التخمين في تحديد وقت إنشاء قوائم جمهور جديدة. بدلاً من ذلك، يمكنك إجراء استطلاعات رخيصة لمعرفة ما إذا كانت قائمة المستخدِمين المتكرّرين متاحة على مدار اليوم لمعرفة ما إذا كانت البيانات الإضافية متاحة.

إنشاء قائمة جمهور متكرّرة

لإنشاء قائمة جمهور متكرّرة، استخدِم الإجراء recurringAudienceLists.create مع العنصر RecurringAudienceList في طلب. المَعلمات التالية مطلوبة:

• اسم جمهور صالح في حقل audience ، بالتنسيق properties/{propertyId}/audiences/{audienceId} يمكنك استخدام الإجراء audiences.list في الإصدار 1 من Google Analytics Admin API للحصول على هذه القيمة. يحتوي حقل 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 لعرض جميع قوائم المستخدمين المتكرّرة لموقع إلكتروني.

استخدام Webhooks لتلقّي إشعارات غير متزامنة بشأن قوائم الجمهور الجديدة

بدلاً من إجراء استطلاع دوري للبيانات الوصفية للإعدادات حول قائمة محددة للجمهور المتكرّر باستخدام الأسلوب recurringAudienceLists.get ، يمكنك تلقّي إشعارات Webhook بشكل غير متزامن عندما تصبح قائمة الجمهور متاحة.

لضبط إشعارات Webhook، حدِّد الحقل webhookNotification عند إنشاء قائمة جمهور متكررة جديدة.

اتّبِع دليل Async audience lists with webhooks لمزيد من المعلومات عن استخدام Webhooks في الإصدار 1 من Google Analytics Data API.

استرداد المستخدِمين في عملية تصدير شريحة جمهور

لاسترداد المستخدمين في عملية تصدير شرائح الجمهور، يمكنك استدعاء الأسلوب 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
}