Elenchi dei segmenti di pubblico ricorrenti

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 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 le appartenenze ai segmenti di pubblico cambiano, per assicurarti di lavorare con i dati più recenti.

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

Creare un nuovo elenco dei segmenti di pubblico ogni giorno

L'elaborazione dei dati dei segmenti di pubblico di un giorno e l'aggiornamento dell'appartenenza richiedono un periodo di tempo variabile. Non è possibile essere certi che i dati dell'elenco dei segmenti di pubblico vengano aggiornati entro 24 ore.

Ad esempio, anche se richiedi un elenco dei segmenti di pubblico alla stessa ora ogni giorno, in alcuni giorni l'elenco dei segmenti di pubblico sarà lo stesso del giorno precedente, mentre in altri giorni sarà diverso e conterrà un giorno aggiuntivo di modifiche all'appartenenza.

Creazione giornaliera di un nuovo elenco del segmento di pubblico

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

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ù indovinare quando creare nuovi elenchi dei segmenti di pubblico. In alternativa, puoi eseguire il polling dell'elenco dei segmenti di pubblico ricorrente a basso costo durante il giorno per verificare se sono disponibili dati aggiuntivi.

Esecuzione periodica del polling di un elenco del segmento di pubblico ricorrente durante il giorno

Creare un elenco dei segmenti di pubblico ricorrente

Per creare un elenco dei segmenti di pubblico ricorrente, chiama il recurringAudienceLists.create metodo utilizzando l' RecurringAudienceList oggetto in una richiesta. Sono necessari i seguenti parametri:

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

Ecco una richiesta di creazione di un elenco dei segmenti di pubblico ricorrente di esempio:

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 di questo elenco dei segmenti di pubblico ricorrente. Inoltre, i metadati di configurazione contengono i nomi delle risorse per le istanze dell'elenco dei segmenti di pubblico create 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"
  ]
}

Eseguire il polling dei metadati di configurazione

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

Ecco un esempio:

Richiesta HTTP

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

Nella risposta viene restituita un'istanza di RecurringAudienceList. Contiene i metadati di configurazione, inclusi i nomi delle risorse per le istanze dell'elenco dei segmenti di pubblico create 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à.

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 ricorrente specifico utilizzando il recurringAudienceLists.get metodo, puoi ricevere in modo asincrono le notifiche webhook quando un elenco dei segmenti di pubblico diventa disponibile.

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

Per ulteriori informazioni sull'utilizzo dei webhook nell'API Google Analytics Data v1, consulta la guida Async audience lists with webhooks.

Recuperare gli utenti in un'esportazione dei segmenti di pubblico

Per recuperare gli utenti in un'esportazione dei segmenti di pubblico, chiama il audienceExports.query metodo 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
}