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 formatoproperties/{propertyId}/audiences/{audienceId}
. Per ottenere questo valore, puoi utilizzare il metodoaudiences.list
dell'API Google Analytics Admin v1. Il campoAudience.name
della rispostaaudiences.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
}