Wiederkehrende Zielgruppenlisten

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

Bei wiederkehrenden Zielgruppenlisten werden täglich Zielgruppenlisten erstellt, wenn sich die Zielgruppenmitgliedschaften ändern. So arbeiten Sie immer mit den neuesten Daten.

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

Täglich eine neue Zielgruppenliste erstellen

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

Auch wenn Sie eine Zielgruppenliste jeden Tag zur gleichen Zeit anfordern, ist sie an manchen Tagen mit der des Vortags identisch. An anderen Tagen ist sie anders und enthält einen zusätzlichen Tag mit Änderungen an 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 die Daten der beiden Vortage verwendet. Wenn Sie eine Zielgruppenliste nach den täglichen Aktualisierungen der Mitgliedschaft erstellen, werden die Daten von gestern verwendet.

Wiederkehrende Zielgruppenliste regelmäßig abfragen

Wiederkehrende Zielgruppenlisten werden nur 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 wiederkehrende Zielgruppenliste im Laufe des Tages kostengünstig abfragen, um zu sehen, ob zusätzliche Daten verfügbar sind.

Regelmäßiges Abfragen 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:

  • Einen gültigen Zielgruppennamen im Feld audience, formatiert als properties/{propertyId}/audiences/{audienceId}. Sie können die Methode audiences.list der Google Analytics Admin API v1 verwenden, um diesen Wert abzurufen. Das Feld Audience.name der audiences.list-Antwort enthält den Namen der Zielgruppe.
  • 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. In einer Zielgruppenliste sind nur die Daten für die in diesem Feld genannten Dimensionen enthalten.

Hier ein Beispiel für eine Anfrage zum Erstellen einer wiederkehrenden Zielgruppenliste:

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 Abfragen verwendet werden kann, um die Konfigurationsmetadaten für diese wiederkehrende Zielgruppenliste abzurufen. Außerdem enthalten die Konfigurationsmetadaten 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 zur Umfragekonfiguration

Verwenden Sie die Methode recurringAudienceLists.get, um Konfigurationsmetadaten zu einer bestimmten wiederkehrenden Zielgruppenliste 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

Als Antwort wird eine Instanz von RecurringAudienceList zurückgegeben. Sie enthält die Konfigurationsmetadaten, einschließlich der Ressourcennamen für Zielgruppenlisten-Instanzen, 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 zu einer bestimmten wiederkehrenden Zielgruppenliste regelmäßig mit der Methode recurringAudienceLists.get abzufragen, können Sie asynchron 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 von recurringAudienceLists.get oder recurringAudienceLists.list abgerufen wurde.

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
}