Elenchi dei segmenti di pubblico ricorrenti

Questo documento descrive gli elenchi di segmenti di pubblico ricorrenti, che sono una funzionalità avanzata della versione 1 dell'API di dati di Google Analytics. Per un'introduzione alla funzionalità di esportazione degli elenchi dei segmenti di pubblico, consulta la guida di base all'esportazione dei segmenti di pubblico.

Gli elenchi dei segmenti di pubblico ricorrenti generano elenchi dei segmenti di pubblico ogni giorno man mano che cambiano le relative adesioni, per assicurarti di utilizzare i dati più recenti.

Gli elenchi dei segmenti di pubblico regolari (non ricorrenti) sono elenchi statici degli utenti nel segmento di pubblico al momento della generazione dell'elenco.

Creare un nuovo elenco del segmento di pubblico ogni giorno

L'elaborazione dei dati sul pubblico di un giorno e l'aggiornamento dell'abbonamento richiedono un tempo variabile. Non è possibile avere la certezza che i dati dell'elenco del segmento di pubblico vengano aggiornati in 24 ore.

Ad esempio, anche se richiedi un elenco del segmento di pubblico alla stessa ora ogni giorno, in alcuni giorni l'elenco del segmento di pubblico sarà uguale a quello del giorno precedente, mentre in altri giorni sarà diverso e contiene un giorno aggiuntivo di modifiche all'appartenenza.

Creazione di un nuovo elenco del segmento di pubblico ogni giorno

Gli elenchi dei segmenti di pubblico si basano sui dati sugli eventi del giorno precedente alle modifiche più recenti dell'appartenenza. Se crei un elenco del segmento di pubblico prima degli aggiornamenti giornalieri dell'appartenenza, verranno utilizzati i dati dei due giorni precedenti. Se crei un elenco del segmento di pubblico dopo gli aggiornamenti giornalieri dell'appartenenza, verranno utilizzati i dati di ieri.

Eseguire periodicamente il polling di un elenco dei segmenti di pubblico ricorrente

Gli elenchi dei segmenti di pubblico ricorrenti generano elenchi dei segmenti di pubblico solo quando sono disponibili i dati di un giorno aggiuntivo. In questo modo non dovrai più decidere quando creare nuovi elenchi di segmenti di pubblico. In alternativa, puoi eseguire il polling dell'elenco dei segmenti di pubblico ricorrenti durante la giornata a un costo ridotto per verificare se sono disponibili dati aggiuntivi.

Eseguire periodicamente il polling di un elenco del segmento di pubblico ricorrente durante il giorno

Creare un elenco del segmento di pubblico ricorrente

Per creare un elenco del segmento di pubblico ricorrente, chiama il metodo recurringAudienceLists.create utilizzando l'oggetto RecurringAudienceList in una richiesta. I seguenti parametri sono obbligatori:

  • Un nome segmento di pubblico valido nel campo audience, formato come properties/{propertyId}/audiences/{audienceId}. Per ottenere questo valore, puoi utilizzare il metodo audiences.list dell'API Google Analytics Admin v1. Il campo Audience.name della risposta audiences.list contiene il nome del segmento di pubblico.
  • Un elenco valido di dimensioni nel campo dimensions. L'elenco delle dimensioni supportate da questo metodo è disponibile nella documentazione relativa allo schema di esportazione dei segmenti di pubblico. Solo i dati relativi alle dimensioni menzionate in questo campo sono inclusi in un elenco del segmento di pubblico.

Di seguito è riportato un esempio di richiesta di creazione di un elenco del segmento di pubblico ricorrente:

Richiesta HTTP

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

Una risposta del metodo recurringAudienceLists.create contiene il nome nel campo name (ad esempio properties/1234567/recurringAudienceLists/123), che può essere utilizzato nelle query successive per recuperare i metadati di configurazione per questo elenco del segmento di pubblico ricorrente. Inoltre, i metadati di configurazione contengono nomi di risorse per le istanze dell'elenco del segmento di pubblico create per questo elenco del segmento di pubblico ricorrente.

Risposta HTTP

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

Metadati di configurazione del sondaggio

Utilizza il metodo recurringAudienceLists.get per recuperare i metadati di configurazione relativi a un elenco di segmenti di pubblico ricorrenti specifico. I metadati di configurazione contengono nomi di risorse per le istanze dell'elenco del segmento di pubblico create per questo elenco del segmento di pubblico ricorrente.

Ecco un esempio:

Richiesta HTTP

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

In risposta viene restituita un'istanza di RecurringAudienceList. Contiene i metadati di configurazione, tra cui i nomi delle risorse per le istanze dell'elenco del segmento di pubblico creati per questo elenco del segmento di pubblico ricorrente.

Risposta HTTP

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

Puoi utilizzare recurringAudienceLists.list per elencare tutti gli elenchi dei segmenti di pubblico ricorrenti per una proprietà.

Utilizzare i webhook per ricevere notifiche asincrone sui nuovi elenchi dei segmenti di pubblico

Anziché eseguire periodicamente il polling dei metadati di configurazione di un elenco dei segmenti di pubblico ricorrenti specifico utilizzando il metodo recurringAudienceLists.get, puoi ricevere notifiche Webhook in modo asincrono quando un elenco dei segmenti di pubblico diventa disponibile.

Per configurare le notifiche webhook, specifica il campo webhookNotification quando crei un nuovo elenco del segmento di pubblico ricorrente.

Segui la guida Async audience lists with webhooks per saperne di più sull'utilizzo degli webhook nell'API di dati di Google Analytics v1.

Recuperare gli utenti in un'esportazione del segmento di pubblico

Per recuperare gli utenti in un'esportazione di segmenti di pubblico, chiama il metodo audienceExports.query e specifica il nome dell'esportazione di segmenti di pubblico recuperato dai metadati di configurazione forniti da recurringAudienceLists.get o recurringAudienceLists.list.

Richiesta HTTP

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

Se l'esportazione del segmento di pubblico è pronta, viene restituita una risposta contenente l'elenco degli utenti di un segmento di pubblico:

Risposta 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
}