Wiederkehrende Zielgruppenlisten

In diesem Dokument werden wiederkehrende Zielgruppenlisten beschrieben. Das ist eine erweiterte Funktion der Google Analytics Data API v1. Eine Einführung in das Feature zum Exportieren von Zielgruppenlisten finden Sie im Leitfaden zu den Grundlagen des Zielgruppenexports.

Bei wiederkehrenden Zielgruppenlisten werden täglich Zielgruppenlisten erstellt, wenn sich die Zielgruppenmitgliedschaft ändert. So haben Sie immer Zugriff auf die neuesten Daten.

Reguläre (nicht wiederkehrende) Zielgruppenlisten sind statische Listen von Nutzern in der Zielgruppe zum Zeitpunkt der Listengenerierung.

Täglich eine neue Zielgruppenliste erstellen

Die Verarbeitung der Zielgruppendaten eines Tages und die Aktualisierung der Mitgliedschaft dauert unterschiedlich lange. Es gibt keine Möglichkeit, sicherzustellen, dass die Daten der Zielgruppenliste innerhalb von 24 Stunden aktualisiert werden.

Auch wenn Sie beispielsweise jeden Tag zur selben Zeit eine Zielgruppenliste anfordern, ist sie an manchen Tagen identisch mit der Liste vom Vortag. An anderen Tagen ist sie jedoch anders und enthält zusätzliche Änderungen bei der Mitgliedschaft.

Täglich eine neue Zielgruppenliste erstellen

Zielgruppenlisten basieren auf Ereignisdaten vom Tag vor den letzten Änderungen der Mitgliedschaft. Wenn Sie eine Zielgruppenliste erstellen, bevor die täglichen Aktualisierungen der Mitgliedschaft erfolgen, werden Daten aus den beiden Tagen davor verwendet. Wenn Sie eine Zielgruppenliste erstellen, nachdem die täglichen Mitgliedschaftsaktualisierungen erfolgt sind, werden Daten von gestern verwendet.

Wiederkehrende Zielgruppenliste regelmäßig abrufen

Für wiederkehrende Zielgruppenlisten werden nur Zielgruppenlisten erstellt, wenn Daten für einen zusätzlichen Tag verfügbar sind. So müssen Sie nicht mehr raten, wann Sie neue Zielgruppenlisten erstellen sollten. Stattdessen können Sie die Liste mit wiederkehrenden Zielgruppen den ganzen Tag über kostengünstig abfragen, um zu sehen, ob zusätzliche Daten verfügbar sind.

Regelmäßiges Abrufen einer wiederkehrenden Zielgruppenliste im Laufe des Tages

Wiederkehrende Zielgruppenliste erstellen

Wenn Sie eine wiederkehrende Zielgruppenliste erstellen möchten, rufen Sie die Methode recurringAudienceLists.create mit dem Objekt RecurringAudienceList in einer Anfrage auf. Folgende Parameter sind erforderlich:

  • Ein gültiger Zielgruppenname im Feld audience, formatiert als properties/{propertyId}/audiences/{audienceId}. Sie können diesen Wert mit der Methode audiences.list der Google Analytics Admin API v1 abrufen. Das Feld Audience.name der audiences.list-Antwort enthält den Zielgruppennamen.
  • Eine gültige Liste von Dimensionen im Feld dimensions. Eine Liste der von dieser Methode unterstützten Dimensionen finden Sie in der Dokumentation zum Schema für den Zielgruppenexport. Nur die Daten für die in diesem Feld genannten Dimensionen werden in eine Zielgruppenliste aufgenommen.

Hier ist ein Beispiel für eine wiederkehrende Anfrage zum Erstellen von Zielgruppenlisten:

HTTP-Anfrage

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Eine Antwort der Methode recurringAudienceLists.create enthält den Namen im Feld name (z. B. properties/1234567/recurringAudienceLists/123), der in nachfolgenden Anfragen verwendet werden kann, um die Konfigurationsmetadaten für diese Liste mit wiederkehrenden Zielgruppen abzurufen. Die Konfigurationsmetadaten enthalten außerdem Ressourcennamen für Zielgruppenlisteninstanzen, die für diese wiederkehrende Zielgruppenliste erstellt wurden.

HTTP-Antwort

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Metadaten der Umfragekonfiguration abrufen

Verwenden Sie die Methode recurringAudienceLists.get, um Konfigurationsmetadaten zu einer bestimmten Liste mit wiederkehrenden Zielgruppen abzurufen. Die Konfigurationsmetadaten enthalten Ressourcennamen für Zielgruppenlisteninstanzen, die für diese wiederkehrende Zielgruppenliste erstellt wurden.

Beispiel:

HTTP-Anfrage

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

In der Antwort wird eine Instanz von RecurringAudienceList zurückgegeben. Sie enthält die Konfigurationsmetadaten, einschließlich Ressourcennamen für Zielgruppenlisteninstanzen, die für diese wiederkehrende Zielgruppenliste erstellt wurden.

HTTP-Antwort

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Mit recurringAudienceLists.list können Sie alle wiederkehrenden Zielgruppenlisten für eine Property auflisten.

Webhooks verwenden, um asynchrone Benachrichtigungen zu neuen Zielgruppenlisten zu erhalten

Anstatt die Konfigurationsmetadaten für eine bestimmte wiederkehrende Zielgruppenliste regelmäßig mit der Methode recurringAudienceLists.get abzurufen, können Sie asynchrone Webhook-Benachrichtigungen erhalten, wenn eine Zielgruppenliste verfügbar wird.

Wenn Sie Webhook-Benachrichtigungen konfigurieren möchten, geben Sie beim Erstellen einer neuen wiederkehrenden Zielgruppenliste das Feld webhookNotification an.

Weitere Informationen zur Verwendung von Webhooks in der Google Analytics Data API v1 finden Sie im Async audience lists with webhooks-Leitfaden.

Nutzer in einem Zielgruppenexport abrufen

Wenn Sie Nutzer in einem Zielgruppenexport abrufen möchten, rufen Sie die Methode audienceExports.query auf und geben Sie den Namen des Zielgruppenexports an, der aus den Konfigurationsmetadaten abgerufen wurde, die von recurringAudienceLists.get oder recurringAudienceLists.list bereitgestellt werden.

HTTP-Anfrage

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

Wenn der Zielgruppenexport bereit ist, wird eine Antwort mit der Liste der Nutzer in einer Zielgruppe zurückgegeben:

HTTP-Antwort

{
  "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
}