Creare una definizione del segmento utilizzando l’API del servizio di segmentazione
Questo documento fornisce un tutorial per sviluppare, testare, visualizzare in anteprima e salvare una definizione di segmento utilizzando Adobe Experience Platform Segmentation Service API.
Per informazioni su come creare definizioni di segmenti utilizzando l'interfaccia utente, consulta la guida del Generatore di segmenti.
Introduzione
Questo tutorial richiede una buona conoscenza dei vari servizi Adobe Experience Platform coinvolti nella creazione delle definizioni dei segmenti. Prima di iniziare questo tutorial, consulta la documentazione dei seguenti servizi:
- Real-Time Customer Profile: fornisce un profilo consumer unificato e in tempo reale basato su dati aggregati provenienti da più origini.
- Adobe Experience Platform Segmentation Service: consente di creare tipi di pubblico utilizzando definizioni di segmenti o altre origini esterne dai dati del profilo cliente in tempo reale.
- Experience Data Model (XDM): framework standardizzato tramite il quale Platform organizza i dati sull'esperienza del cliente. Per utilizzare al meglio la segmentazione, assicurati che i dati vengano acquisiti come profili ed eventi in base alle best practice per la modellazione dei dati.
Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per effettuare correttamente chiamate alle API Platform.
Lettura delle chiamate API di esempio
Questo tutorial fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un codice JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform.
Raccogliere i valori per le intestazioni richieste
Per effettuare chiamate alle API Platform, devi prima completare l'esercitazione di autenticazione. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:
- Autorizzazione: Bearer
{ACCESS_TOKEN} - x-api-key:
{API_KEY} - x-gw-ims-org-id:
{ORG_ID}
Tutte le risorse in Experience Platform sono isolate in specifiche sandbox virtuali. Tutte le richieste alle API Platform richiedono un'intestazione che specifichi il nome della sandbox in cui verrà eseguita l'operazione:
- x-sandbox-name:
{SANDBOX_NAME}
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:
- Content-Type: application/json
Sviluppare una definizione di segmento
Il primo passaggio nella segmentazione consiste nel definire una definizione di segmento. Una definizione di segmento è un oggetto che incapsula una query scritta in Profile Query Language (PQL). Questo oggetto è anche denominato predicato PQL. I predicati PQL definiscono le regole per la definizione del segmento in base alle condizioni relative a qualsiasi record o serie temporale fornito a Real-Time Customer Profile. Per ulteriori informazioni sulla scrittura di query PQL, consulta la guida di PQL.
È possibile creare una nuova definizione di segmento effettuando una richiesta POST all'endpoint /segment/definitions nell'API Segmentation. L’esempio seguente illustra come formattare una richiesta di definizione, incluse le informazioni necessarie per la corretta definizione di una definizione di segmento.
Per una spiegazione dettagliata su come definire una definizione di segmento, consulta la guida per gli sviluppatori di definizioni di segmento.
Stimare e visualizzare in anteprima un pubblico estimate-and-preview-an-audience
Durante lo sviluppo della definizione del segmento, è possibile utilizzare gli strumenti di stima e anteprima in Real-Time Customer Profile per visualizzare informazioni di riepilogo che consentono di isolare il pubblico previsto. Le stime forniscono informazioni statistiche su una definizione di segmento, ad esempio la dimensione del pubblico prevista e l’intervallo di affidabilità. Le anteprime forniscono elenchi impaginati di profili idonei per la definizione di un segmento, consentendo di confrontare i risultati rispetto a quelli previsti.
Stimando e visualizzando in anteprima il pubblico, puoi testare e ottimizzare i predicati di PQL fino a quando non producono un risultato desiderato, che può quindi essere utilizzato in una definizione di segmento aggiornata.
Per visualizzare in anteprima o stimare la definizione del segmento sono necessari due passaggi:
- Creare un processo di anteprima
- Visualizza la stima o l'anteprima utilizzando l'ID del processo di anteprima
Come vengono generate le stime
Quando i dati abilitati per Real-Time Customer Profile vengono acquisiti in Platform, vengono memorizzati nell’archivio dati Profile. Quando l’acquisizione dei record nell’archivio profili aumenta o diminuisce il conteggio totale dei profili di oltre il 5%, viene attivato un processo di campionamento per aggiornare il conteggio. Se il conteggio dei profili non cambia di oltre il 5%, il processo di campionamento viene eseguito automaticamente su base settimanale.
Il modo in cui il campione viene attivato dipende dal tipo di acquisizione utilizzata:
- Per i flussi di lavoro di dati in streaming, viene eseguito un controllo su base oraria per determinare se la soglia di aumento o riduzione del 5% è stata raggiunta. Se questa soglia è stata raggiunta, viene attivato automaticamente un processo di esempio per aggiornare il conteggio.
- Per l’acquisizione batch, entro 15 minuti dalla corretta acquisizione di un batch nell’archivio profili, se viene raggiunta la soglia di aumento o di riduzione del 5%, viene eseguito un processo per aggiornare il conteggio. Utilizzando l’API di profilo è possibile visualizzare in anteprima l’ultimo processo di esempio riuscito, nonché elencare la distribuzione del profilo per set di dati e per spazio dei nomi dell’identità.
La dimensione del campione dipende dal numero complessivo di entità nell’archivio profili. Queste dimensioni di esempio sono rappresentate nella tabella seguente:
Le stime generalmente durano 10-15 secondi, a partire da una stima approssimativa e con la lettura di più record.
Creare un processo di anteprima
È possibile creare un nuovo processo di anteprima effettuando una richiesta POST all'endpoint /preview.
Istruzioni dettagliate sulla creazione di un processo di anteprima sono disponibili nella guida degli endpoint per anteprime e stime.
Visualizzare una stima o un’anteprima
I processi di stima e anteprima vengono eseguiti in modo asincrono in quanto il completamento di query diverse può richiedere tempi diversi. Una volta avviata una query, puoi utilizzare le chiamate API per recuperare (GET) lo stato corrente della stima o dell’anteprima durante l’avanzamento.
Utilizzando l'API Segmentation Service, è possibile cercare lo stato corrente di un processo di anteprima in base al relativo ID. Se lo stato è "RESULT_READY", è possibile visualizzare i risultati. Per cercare lo stato corrente di un processo di anteprima, leggere la sezione su recupero di una sezione del processo di anteprima nella guida degli endpoint per anteprime e stime. Per cercare lo stato corrente di un processo di stima, leggere la sezione relativa al recupero di un processo di stima nella guida delle anteprime e degli endpoint di stima.
Passaggi successivi
Dopo aver sviluppato, testato e salvato la definizione del segmento, puoi creare un processo per segmenti per creare un pubblico utilizzando l'API Segmentation Service. Consulta il tutorial su valutazione e accesso ai risultati dei segmenti per i passaggi dettagliati su come eseguire questa operazione.