Elenchi dei segmenti di pubblico ricorrenti

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

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

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

Creare un nuovo elenco del segmento di pubblico ogni giorno

L'elaborazione dei dati relativi al pubblico di un giorno e l'aggiornamento dell'abbonamento richiede tempo variabile. Non è possibile essere sicuri che i dati degli elenchi del segmento di pubblico vengano aggiornati entro 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 l'elenco sarà diverso e conterrà un altro giorno di modifiche all'appartenenza.

Gli elenchi dei segmenti di pubblico si basano sui dati sugli eventi di un giorno prima delle modifiche più recenti agli abbonamenti. Se crei un elenco del segmento di pubblico prima dell'aggiornamento giornaliero dell'appartenenza, verranno utilizzati i dati dei due giorni precedenti. Se crei un elenco del segmento di pubblico dopo aver eseguito gli aggiornamenti giornalieri dell'abbonamento, questo utilizzerà i dati del giorno precedente.

Sondaggio periodico su un elenco del segmento di pubblico ricorrente

Gli elenchi dei segmenti di pubblico ricorrenti generano elenchi dei segmenti di pubblico solo quando sono disponibili dati per un giorno aggiuntivo. In questo modo, non dovrai più chiederti quando creare nuovi elenchi dei segmenti di pubblico. Puoi però sottoporre a sondaggi l'elenco del segmento di pubblico ricorrente in modo economico nell'arco della giornata per verificare se sono disponibili dati aggiuntivi.

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 del segmento di pubblico valido nel campo audience, con il formato 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.

Ecco 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 i nomi delle 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 della configurazione dei sondaggi

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

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

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

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

Anziché eseguire il polling periodico dei metadati della configurazione su uno specifico elenco del segmento di pubblico ricorrente utilizzando il metodo recurringAudienceLists.get, puoi ricevere in modo asincrono notifiche webhook quando un elenco del segmento di pubblico diventa disponibile.

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

Consulta la documentazione WebhookNotification per saperne di più sull'utilizzo dei webhook nell'API di dati di Google Analytics v1.

Recuperare gli utenti in un'esportazione dei segmenti di pubblico

Per recuperare gli utenti in un'esportazione dei segmenti di pubblico, chiama il metodo audienceExports.query e specifica il nome dell'esportazione dei 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 dei segmenti di pubblico è pronta, viene restituita una risposta contenente l'elenco degli utenti in 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
}