רשימות קהלים חוזרות

במאמר הזה מתוארות רשימות קהלים חוזרות, שהן תכונה מתקדמת ב-Google Analytics Data API v1. מבוא לתכונת הייצוא של רשימות החברים בקהל זמין במדריך היסודות של ייצוא קהלים.

רשימות קהלים חוזרות יוצרות רשימות קהלים מדי יום בהתאם לשינוי החברויות בקהל, כדי לוודא שאתם עובדים עם הנתונים העדכניים ביותר.

רשימות קהלים רגילות (חוזרות) הן רשימות סטטיות של המשתמשים בקהל בזמן שהרשימה נוצרת.

יצירה של רשימת חברים חדשה מדי יום

יש משך זמן משתנה לעיבוד נתוני הקהל של יום אחד ולעדכון החברות. אין דרך לוודא שהנתונים של רשימת החברים בקהל מתעדכנים 24 שעות.

לדוגמה, גם אם מבקשים רשימת חברים בקהל באותה שעה בכל יום, בימים מסוימים רשימת החברים בקהל תהיה זהה לזו של היום הקודם, ובימים אחרים רשימת החברים בקהל תהיה שונה ותכיל יום נוסף של שינויים ברשימת החברים.

רשימות הקהלים מבוססות על נתוני אירועים מיום אחד לפני השינויים האחרונים במספר החברים. אם יוצרים רשימת חברים בקהל לפני העדכון של מספר החברים בכל יום, היא תשתמש בנתונים מהיומיים שלפני כן. אם יוצרים רשימת חברים בקהל אחרי העדכון היומי של מספר החברים, היא מתבססת על הנתונים מאתמול.

בדיקה תקופתית של רשימת חברים בקהל

רשימות קהלים חוזרות יוצרות רשימות קהלים רק כשיש נתונים של יום נוסף. כך לא צריך לנחש מתי ליצור רשימות קהלים חדשות. במקום זאת, אפשר לערוך סקר קצר של רשימת הקהלים הקבועה לאורך היום כדי לבדוק אם יש נתונים נוספים.

יצירה של רשימת קהלים חוזרת

כדי ליצור רשימה חוזרת של חברים בקהל, צריך להפעיל את השיטה recurringAudienceLists.create באמצעות האובייקט RecurringAudienceList שבבקשה. הפרמטרים הבאים נדרשים:

• שם קהל חוקי בשדה audience, בפורמט properties/{propertyId}/audiences/{audienceId}. כדי לקבל את הערך הזה, אפשר להשתמש ב-method 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"
    }
  ]
}

תשובה מ-method 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"
  ]
}

מטא-נתונים של הגדרת הסקר

משתמשים ב-method 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 כדי להציג רשימה של כל רשימות הקהלים החוזרות עבור נכס מסוים.

משתמשים בפעולות webhook כדי לקבל התראות אסינכרוניות על רשימות קהלים חדשות

במקום לדגום מדי פעם את המטא-נתונים של ההגדרות לגבי רשימה ספציפית של חברים בקהל, באמצעות השיטה recurringAudienceLists.get, תוכלו לקבל באופן אסינכרוני התראות על תגובה לפעולה מאתר אחר (webhook) כשרשימת החברים בקהל תהיה זמינה.

כדי להגדיר התראות על תגובה לפעולה מאתר אחר (webhook), צריך לציין את השדה webhookNotification כשיוצרים רשימה חוזרת חדשה של חברים בקהל.

מידע נוסף על השימוש ב-webhooks ב-Google Analytics Data API v1 זמין במסמכי התיעוד בנושא WebhookNotification.

אחזור משתמשים בייצוא קהלים

כדי לאחזר משתמשים בייצוא קהלים, צריך להפעיל את השיטה 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
}