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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי להגדיר התראות Webhook, צריך לציין את השדה webhookNotification כשיוצרים רשימה חוזרת חדשה של חברים בקהל.

במדריך Async audience lists with webhooks מפורט מידע נוסף על השימוש בתגובות לפעולה מאתר אחר (webhook) ב-Google Analytics Data API v1.

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

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