Questo documento descrive gli elenchi dei segmenti di pubblico ricorrenti, una funzionalità avanzata dell'API Google Analytics Data v1. Per un'introduzione alla funzionalità di esportazione degli elenchi dei segmenti di pubblico, consulta la guida ai concetti fondamentali sull'esportazione dei segmenti di pubblico.
Gli elenchi dei segmenti di pubblico ricorrenti generano elenchi dei segmenti di pubblico ogni giorno in base alle modifiche alle iscrizioni ai segmenti di pubblico, per assicurarti di lavorare con i dati più recenti.
Gli elenchi dei segmenti di pubblico regolari (non ricorrenti) sono elenchi statici di utenti nel segmento di pubblico al momento della generazione dell'elenco.
Crea un nuovo elenco del segmento di pubblico ogni giorno
L'elaborazione dei dati sul segmento di pubblico di un giorno e l'aggiornamento dell'appartenenza richiedono un periodo di tempo variabile. Non è possibile avere la certezza che i dati dell'elenco 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à lo stesso del giorno precedente, mentre in altri sarà diverso e conterrà un giorno aggiuntivo di modifiche all'appartenenza.
Gli elenchi dei segmenti di pubblico si basano sui dati sugli eventi del giorno precedente alle modifiche più recenti all'appartenenza. Se crei un elenco del segmento di pubblico prima degli aggiornamenti giornalieri delle iscrizioni, verranno utilizzati i dati dei due giorni precedenti. Se crei un elenco del segmento di pubblico dopo gli aggiornamenti giornalieri dell'iscrizione, verranno utilizzati i dati del giorno precedente.
Esegui periodicamente il polling di 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 di un giorno aggiuntivo. In questo modo, non dovrai più indovinare quando creare nuovi elenchi dei segmenti di pubblico. In alternativa, puoi eseguire il polling dell'elenco del segmento di pubblico ricorrente durante il giorno per verificare se sono disponibili dati aggiuntivi.
Crea 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 di pubblico valido nel campo
audience, formattato comeproperties/{propertyId}/audiences/{audienceId}. Per ottenere questo valore, puoi utilizzare il metodoaudiences.listdell'API Google Analytics Admin v1. Il campoAudience.namedella rispostaaudiences.listcontiene 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 dello schema di esportazione dei segmenti di pubblico. In un elenco del segmento di pubblico vengono inclusi solo i dati relativi alle dimensioni menzionate in questo campo.
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 i nomi delle risorse per le istanze degli elenchi dei segmenti di pubblico creati per questo elenco dei segmenti 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 del segmento di pubblico ricorrente specifico. I metadati di configurazione contengono i nomi delle risorse per le istanze degli elenchi dei segmenti di pubblico creati per questo elenco dei segmenti 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, che includono i nomi delle risorse per le istanze degli elenchi dei segmenti di pubblico creati per questo elenco dei segmenti 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à.
Utilizza i webhook per ricevere notifiche asincrone sui nuovi elenchi dei segmenti di pubblico
Anziché eseguire periodicamente il polling dei metadati di configurazione relativi a un elenco del segmento di pubblico ricorrente specifico utilizzando il metodo recurringAudienceLists.get, puoi ricevere notifiche webhook in modo asincrono 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.
Segui la guida Async audience lists with webhooks per saperne di più sull'utilizzo dei webhook nell'API Google Analytics Data v1.
Recupera gli utenti in un'esportazione dei segmenti di pubblico
Per recuperare gli utenti in un'esportazione del segmento di pubblico, chiama il metodo audienceExports.query e specifica il nome dell'esportazione del segmento 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 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
}