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 di segmenti di pubblico, consulta la guida alle nozioni di base sull'esportazione dei segmenti di pubblico.

Gli elenchi dei segmenti di pubblico ricorrenti vengono generati quotidianamente man mano che cambiano le appartenenze 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.

Creare un nuovo elenco dei segmenti di pubblico ogni giorno

L'elaborazione dei dati del pubblico di un giorno e l'aggiornamento dell'iscrizione richiedono un periodo di tempo variabile. Non è possibile avere la certezza che i dati dell'elenco dei segmenti 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 giorni sarà diverso e conterrà un giorno aggiuntivo di modifiche all'appartenenza.

Creazione giornaliera di un nuovo elenco di segmenti di pubblico

Gli elenchi dei segmenti di pubblico si basano sui dati degli eventi del giorno precedente alle modifiche all'iscrizione più recenti. Se crei un elenco di segmenti di pubblico prima che vengano eseguiti gli aggiornamenti giornalieri dell'appartenenza, verranno utilizzati i dati dei due giorni precedenti. Se crei un elenco di segmenti di pubblico dopo gli aggiornamenti giornalieri delle iscrizioni, 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 vengono generati solo quando sono disponibili dati aggiuntivi per un giorno. In questo modo non dovrai più decidere quando creare nuovi elenchi di pubblico. In alternativa, puoi eseguire il polling a basso costo dell'elenco dei segmenti di pubblico ricorrenti 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 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. Sono necessari i seguenti parametri:

  • Un nome segmento di pubblico valido nel campo audience, formattato come properties/{propertyId}/audiences/{audienceId}. Puoi utilizzare il metodo audiences.list 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 campo dimensions. L'elenco delle dimensioni supportate da questo metodo è disponibile nella documentazione Schema di esportazione dei segmenti di pubblico. Nell'elenco dei segmenti di pubblico vengono inclusi solo i dati per le dimensioni menzionate in questo campo.

Di seguito è riportato un esempio di richiesta di creazione di un elenco dei segmenti 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 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"
  ]
}

Metadati di configurazione del sondaggio

Utilizza il metodo recurringAudienceLists.get per recuperare i metadati di configurazione di un elenco di segmenti di pubblico ricorrenti specifico. 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.

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 di segmenti di pubblico

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

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

Per saperne di più sull'utilizzo dei webhook nell'API di dati di Google Analytics v1, consulta la guida Async audience lists with webhooks.

Recuperare gli utenti in un'esportazione di segmenti 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
}