Valutare e accedere ai risultati dei segmenti

Questo documento fornisce un'esercitazione per valutare i segmenti e accedere ai risultati dei segmenti utilizzando Segmentation API.

Introduzione

Questa esercitazione richiede una comprensione approfondita dei vari servizi Adobe Experience Platform coinvolti nella creazione di segmenti di pubblico. Prima di iniziare questa esercitazione, consulta la documentazione relativa ai seguenti servizi:

  • Real-time Customer Profile: Fornisce un profilo cliente unificato in tempo reale basato su dati aggregati provenienti da più origini.
  • Adobe Experience Platform Segmentation Service: Ti consente di creare segmenti di pubblico dai Real-time Customer Profile dati.
  • Experience Data Model (XDM): Il framework standardizzato tramite il quale Platform organizza i dati sulla customer experience.
  • Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola Platform istanza in ambienti virtuali separati per sviluppare e sviluppare applicazioni di esperienza digitale.

Intestazioni richieste

Questa esercitazione richiede anche di aver completato l' esercitazione sull'autenticazione per effettuare correttamente le chiamate alle API Platform . Il completamento dell’esercitazione di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come mostrato di seguito:

  • Autorizzazione: Portatore {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Tutte le risorse in Experience Platform sono isolate in sandbox virtuali specifiche. Le richieste alle API Platform richiedono un’intestazione che specifichi il nome della sandbox in cui avrà luogo l’operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Per ulteriori informazioni sulle sandbox in Platform, consulta la documentazione di panoramica sandbox.

Tutte le richieste di POST, PUT e PATCH richiedono un’intestazione aggiuntiva:

  • Tipo di contenuto: application/json

Valutare un segmento

Dopo aver sviluppato, testato e salvato la definizione del segmento, puoi valutarlo tramite una valutazione programmata o on demand.

La valutazione pianificata (nota anche come "segmentazione pianificata") consente di creare una pianificazione periodica per l’esecuzione di un processo di esportazione in un momento specifico, mentre la valutazione on demand comporta la creazione di un processo di segmento per generare immediatamente il pubblico. I passaggi per ciascuno di essi sono descritti di seguito.

Se non hai ancora completato l'esercitazione crea un segmento utilizzando l'API di segmentazione o creato una definizione di segmento utilizzando Generatore di segmenti, procedi prima di procedere con questa esercitazione.

Valutazione programmata

Tramite la valutazione pianificata, l’organizzazione IMS può creare una pianificazione ricorrente per eseguire automaticamente i processi di esportazione.

NOTA

La valutazione pianificata può essere abilitata per le sandbox con un massimo di cinque (5) criteri di unione per XDM Individual Profile. Se la tua organizzazione dispone di più di cinque criteri di unione per XDM Individual Profile all’interno di un singolo ambiente sandbox, non potrai utilizzare la valutazione pianificata.

Creare una pianificazione

Effettuando una richiesta POST all’endpoint /config/schedules, puoi creare una pianificazione e includere l’ora specifica in cui deve essere attivata la pianificazione.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida degli endpoint programmati

Abilita pianificazione

Per impostazione predefinita, una pianificazione è inattiva quando viene creata a meno che la proprietà state non sia impostata su active nel corpo della richiesta di creazione (POST). Puoi abilitare una pianificazione (imposta state su active) effettuando una richiesta PATCH all’endpoint /config/schedules e includendo l’ID della pianificazione nel percorso.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida degli endpoint programmati

Aggiornare l’ora di pianificazione

È possibile aggiornare i tempi di pianificazione effettuando una richiesta PATCH all’ endpoint /config/schedules e includendo l’ID della pianificazione nel percorso.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida degli endpoint programmati

Valutazione su richiesta

La valutazione su richiesta consente di creare un processo di segmento per generare un segmento di pubblico ogni volta che lo desideri. A differenza della valutazione pianificata, ciò si verifica solo quando richiesto e non è ricorrente.

Creare un processo di segmento

Un processo di segmento è un processo asincrono che crea un nuovo segmento di pubblico. Fa riferimento a una definizione di segmento, nonché a qualsiasi criterio di unione che controlla in che modo Real-time Customer Profile unisce gli attributi sovrapposti nei frammenti di profilo. Quando un processo di segmento viene completato con successo, puoi raccogliere varie informazioni sul segmento, ad esempio eventuali errori verificatisi durante l’elaborazione e le dimensioni finali del pubblico.

Puoi creare un nuovo processo di segmento effettuando una richiesta POST all’endpoint /segment/jobs nell’ API Real-time Customer Profile .

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi di segmento

Cerca lo stato del processo del segmento

È possibile utilizzare id per un processo di segmento specifico per eseguire una richiesta di ricerca (GET) per visualizzare lo stato corrente del processo.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi di segmento

Interpretare i risultati dei segmenti

Quando i processi di segmento vengono eseguiti correttamente, la mappa segmentMembership viene aggiornata per ciascun profilo incluso all’interno del segmento. segmentMembership memorizza anche tutti i segmenti di pubblico valutati in Platform, consentendo l’integrazione con altre soluzioni come Adobe Audience Manager.

L’esempio seguente mostra l’aspetto dell’attributo segmentMembership per ogni record di profilo individuale:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "existing"
      },
      "53cba6b2-a23b-454a-8069-fc41308f1c0f": {
        "lastQualificationTime": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      }
    },
    "Email": {
      "abcd@adobe.com": {
        "lastQualificationTime": "2017-09-26T15:52:25+00:00",
        "status": "exited"
      }
    }
  }
}
Proprietà Descrizione
lastQualificationTime La marca temporale in cui è stata rilasciata l’asserzione dell’appartenenza al segmento e il profilo è entrato o uscito dal segmento.
status Lo stato della partecipazione al segmento come parte della richiesta corrente. Deve essere uguale a uno dei seguenti valori noti:
  • existing: L’entità continua a trovarsi nel segmento.
  • realized: L'entità sta entrando nel segmento.
  • exited: L'entità sta uscendo dal segmento.

Accedere ai risultati dei segmenti

È possibile accedere ai risultati di un processo di segmento in uno dei due modi seguenti: puoi accedere a singoli profili o esportare un intero pubblico in un set di dati.

Le sezioni seguenti descrivono più dettagliatamente queste opzioni.

Cercare un profilo

Se conosci il profilo specifico a cui desideri accedere, puoi farlo utilizzando l’ API Real-time Customer Profile . I passaggi completi per accedere ai singoli profili sono disponibili nell’ esercitazione Access Real-time Customer Profile data using the Profile API (Accesso ai dati del profilo cliente in tempo reale).

Esportare un segmento

Dopo che un processo di segmentazione è stato completato correttamente (il valore dell’attributo status è "SUCCEEDED"), puoi esportare il pubblico in un set di dati a cui è possibile accedere e agire.

Per esportare il pubblico sono necessari i seguenti passaggi:

Creare un set di dati di destinazione

Quando si esporta un pubblico, è necessario creare prima un set di dati di destinazione. È importante che il set di dati sia configurato correttamente per garantire che l’esportazione abbia esito positivo.

Una delle considerazioni chiave è lo schema su cui è basato il set di dati (schemaRef.id nella richiesta di esempio API di seguito). Per esportare un segmento, il set di dati deve essere basato su XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Uno schema di unione è uno schema generato dal sistema e di sola lettura che aggrega i campi degli schemi che condividono la stessa classe, in questo caso si tratta della classe Profilo individuale XDM. Per ulteriori informazioni sugli schemi di visualizzazione dell'unione, consulta la sezione Profilo del cliente in tempo reale della guida per gli sviluppatori del registro dello schema.

Esistono due modi per creare il set di dati necessario:

  • Utilizzo delle API: i passaggi che seguono in questa esercitazione spiegano come creare un set di dati che faccia riferimento a XDM Individual Profile Union Schema utilizzando l’ Catalog API.
  • Utilizzo dell’interfaccia utente: per utilizzare l’interfaccia Adobe Experience Platform utente per creare un set di dati che fa riferimento allo schema di unione, segui i passaggi dell’ esercitazione Interfaccia utente e torna a questa esercitazione per procedere con la generazione dei profili di pubblico.

Se disponi già di un set di dati compatibile e ne conosci l’ID, puoi procedere direttamente al passaggio generazione di profili di pubblico.

Formato API

POST /dataSets

Richiesta

La seguente richiesta crea un nuovo set di dati, fornendo parametri di configurazione nel payload.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "name": "Segment Export",
    "schemaRef": {
        "id": "https://ns.adobe.com/xdm/context/profile__union",
        "contentType": "application/vnd.adobe.xed+json;version=1"
    }
}'
Proprietà Descrizione
name Un nome descrittivo per il set di dati.
schemaRef.id ID della visualizzazione unione (schema) a cui sarà associato il set di dati.

Risposta

Una risposta corretta restituisce un array contenente l’ID univoco generato dal sistema di sola lettura del set di dati appena creato. Per esportare correttamente i membri del pubblico è necessario un ID set di dati configurato correttamente.

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

Generare profili per i membri del pubblico

Una volta che disponi di un set di dati persistente nell’unione, puoi creare un processo di esportazione per mantenere i membri del pubblico nel set di dati effettuando una richiesta POST all’endpoint /export/jobs nell’ API Real-time Customer Profile e fornendo l’ID del set di dati e le informazioni sul segmento per i segmenti che desideri esportare.

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi di esportazione

Monitorare l’avanzamento dell’esportazione

Come processo di esportazione, puoi monitorarne lo stato effettuando una richiesta di GET all’ endpoint /export/jobs e includendo id del processo di esportazione nel percorso. Il processo di esportazione viene completato una volta che il campo status restituisce il valore "SUCCEEDED".

Informazioni più dettagliate sull'utilizzo di questo endpoint sono disponibili nella guida all'endpoint dei processi di esportazione

Passaggi successivi

Una volta completata correttamente l’esportazione, i dati sono disponibili all’interno di Data Lake in Experience Platform. Puoi quindi utilizzare Data Access API per accedere ai dati utilizzando il batchId associato all’esportazione. A seconda delle dimensioni del segmento, i dati possono essere in blocchi e il batch può essere costituito da più file.

Per istruzioni dettagliate su come utilizzare l'API Data Access per accedere e scaricare file batch, segui il tutorial sull'accesso ai dati.

Puoi anche accedere ai dati dei segmenti esportati correttamente utilizzando Adobe Experience Platform Query Service. Utilizzando l’interfaccia utente o l’API RESTful, Query Service puoi scrivere, convalidare ed eseguire query sui dati all’interno di Data Lake.

Per ulteriori informazioni su come eseguire query sui dati del pubblico, consulta la documentazione su Query Service.

In questa pagina