Valutare gli eventi in tempo quasi reale con la segmentazione in streaming

La segmentazione in streaming su Adobe Experience Platform consente ai clienti di eseguire la segmentazione quasi in tempo reale concentrandosi sulla ricchezza dei dati. Con la segmentazione in streaming, la qualificazione dei segmenti ora avviene quando i dati in streaming arrivano in Platform, riducendo la necessità di pianificare ed eseguire processi di segmentazione. Con questa funzionalità è ora possibile valutare la maggior parte delle regole del segmento quando i dati vengono passati in Platform, il che significa che l'appartenenza al segmento verrà mantenuta aggiornata senza eseguire processi di segmentazione pianificati.

Introduzione

Questa guida per sviluppatori richiede una buona conoscenza dei vari servizi Adobe Experience Platform coinvolti nella segmentazione streaming. Prima di iniziare questo tutorial, consulta la documentazione dei seguenti servizi:

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per effettuare correttamente chiamate alle API Platform.

Lettura delle chiamate API di esempio

Questa guida per gli sviluppatori 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:

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:

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:

Per completare richieste specifiche possono essere necessarie intestazioni aggiuntive. Le intestazioni corrette vengono visualizzate in ciascuno degli esempi all'interno di questo documento. Presta particolare attenzione alle richieste di esempio per assicurarti che siano incluse tutte le intestazioni richieste.

Tipi di query abilitati per la segmentazione in streaming query-types

Affinché una definizione di segmento possa essere valutata utilizzando la segmentazione in streaming, la query deve essere conforme alle seguenti linee guida.

Una definizione di segmento non verrà abilitata per la segmentazione in streaming nei seguenti scenari:

Tieni presente che le seguenti linee guida sono applicabili quando esegui la segmentazione in streaming:

Se una definizione di segmento viene modificata in modo da non soddisfare più i criteri per la segmentazione in streaming, la definizione del segmento passerà automaticamente da "Streaming" a "Batch".

Inoltre, l’annullamento del riconoscimento del segmento, in modo simile alla qualificazione del segmento, avviene in tempo reale. Di conseguenza, se un profilo non è più idoneo per la definizione di un segmento, non potrà più essere qualificato immediatamente. Ad esempio, se la definizione del segmento richiede "Tutti gli utenti che hanno acquistato scarpe rosse nelle ultime tre ore", dopo tre ore tutti i profili che si sono inizialmente qualificati per la definizione del segmento non saranno qualificati.

Recupera tutte le definizioni di segmento abilitate per la segmentazione in streaming

Per recuperare un elenco di tutte le definizioni di segmenti abilitate per la segmentazione in streaming all'interno dell'organizzazione, effettua una richiesta di GET all'endpoint /segment/definitions.

Formato API

Per recuperare le definizioni dei segmenti abilitati per lo streaming, è necessario includere il parametro di query evaluationInfo.continuous.enabled=true nel percorso della richiesta.

GET /segment/definitions?evaluationInfo.continuous.enabled=true

Richiesta

curl -X GET \
  'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.continuous.enabled=true' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce un array di definizioni di segmenti nell’organizzazione abilitate per la segmentazione in streaming.

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": " People who are NOT on their homepage ",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": false
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572029711000,
            "updateEpoch": 1572029712000,
            "updateTime": 1572029712000
        },
        {
            "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": "Homepage_continuous",
            "description": "People who are on their homepage - continuous",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572021085000,
            "updateEpoch": 1572021086000,
            "updateTime": 1572021086000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

Creare una definizione di segmento abilitata per lo streaming

Una definizione di segmento sarà automaticamente abilitata per lo streaming se corrisponde a uno dei tipi di segmentazione streaming elencati sopra.

Formato API

POST /segment/definitions

Richiesta

curl -X POST \
  https://platform.adobe.io/data/core/ups/segment/definitions \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'  \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true
        },
        "synchronous": {
            "enabled": false
        }
    }
}'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli della nuova definizione di segmento abilitata per lo streaming.

{
    "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "{SANDBOX_ID}",
        "sandboxName": "{SANDBOX_NAME}",
        "type": "production",
        "default": true
    },
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true,
                   },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1572021085000,
    "updateEpoch": 1572021086000,
    "updateTime": 1572021086000
}

Abilita valutazione pianificata enable-scheduled-segmentation

Una volta abilitata la valutazione in streaming, è necessario creare una linea di base (dopo di che la definizione del segmento sarà sempre aggiornata). La valutazione pianificata (nota anche come segmentazione pianificata) deve prima essere abilitata affinché il sistema esegua automaticamente la baseline. Con la segmentazione pianificata, la tua organizzazione può rispettare una pianificazione ricorrente per eseguire automaticamente processi di esportazione per valutare le definizioni dei segmenti.

Creare una pianificazione

Effettuando una richiesta POST all'endpoint /config/schedules, è possibile creare una pianificazione e includere l'ora specifica in cui attivare la pianificazione.

Formato API

POST /config/schedules

Richiesta

La seguente richiesta crea una nuova pianificazione basata sulle specifiche fornite nel payload.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli della pianificazione appena creata.

{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{ORG_ID}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}

Abilitare una pianificazione

Per impostazione predefinita, una pianificazione non è attiva al momento della creazione, a meno che la proprietà state non sia impostata su active nel corpo della richiesta di creazione (POST). È possibile abilitare una pianificazione (impostare state su active) effettuando una richiesta PATCH all'endpoint /config/schedules e includendo l'ID della pianificazione nel percorso.

Formato API

POST /config/schedules/{SCHEDULE_ID}

Richiesta

La richiesta seguente utilizza la formattazione JSON Patch per aggiornare state della pianificazione a active.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
          "op": "add",
          "path": "/state",
          "value": "active"
        }
      ]'

Risposta

In caso di esito positivo, l’aggiornamento restituisce un corpo di risposta vuoto e lo stato HTTP 204 (nessun contenuto).

La stessa operazione può essere utilizzata per disabilitare una pianificazione sostituendo il "valore" nella richiesta precedente con "inattivo".

Passaggi successivi

Ora che hai abilitato sia le definizioni di segmenti nuove che quelle esistenti per la segmentazione in streaming, sia la segmentazione pianificata per sviluppare una linea di base ed eseguire valutazioni ricorrenti, puoi iniziare a creare definizioni di segmenti abilitati per lo streaming per la tua organizzazione.

Per informazioni su come eseguire azioni simili e lavorare con le definizioni dei segmenti utilizzando l'interfaccia utente di Adobe Experience Platform, visita la guida utente di Segment Builder.

Appendice

Nella sezione seguente sono elencate le domande frequenti sulla segmentazione in streaming:

La segmentazione in streaming "unqualification" (non qualificazione) si verifica anche in tempo reale?

Nella maggior parte dei casi, l’annullamento della qualifica per segmentazione in streaming avviene in tempo reale. Tuttavia, le definizioni dei segmenti in streaming che utilizzano segmenti di segmenti not non sono idonee in tempo reale, ma vengono annullate dopo 24 ore.

Su quali dati funziona la segmentazione in streaming?

La segmentazione in streaming funziona su tutti i dati acquisiti utilizzando un’origine di streaming. I segmenti acquisiti utilizzando un’origine basata su batch vengono valutati di notte, anche se è idoneo per la segmentazione in streaming. Gli eventi inviati in streaming al sistema con una marca temporale precedente alle 24 ore verranno elaborati nel processo batch successivo.

Come vengono definite le definizioni dei segmenti come segmentazione in batch o in streaming?

Una definizione di segmento è definita come segmentazione in batch o in streaming in base a una combinazione di tipo di query e durata della cronologia degli eventi. Nella sezione tipi di query di segmentazione in streaming è disponibile un elenco delle definizioni dei segmenti che verranno valutate come segmenti in streaming.

Tieni presente che se un segmento contiene both un'espressione inSegment e una catena di eventi singola diretta, non può essere qualificato per la segmentazione in streaming. Se desideri che questa definizione di segmento sia idonea per la segmentazione in streaming, devi rendere la catena di eventi singoli diretta la propria definizione di segmento.

Perché il numero di definizioni di segmenti "qualificati totali" continua a crescere mentre il numero in "Ultimi X giorni" rimane pari a zero nella sezione dei dettagli di definizione del segmento?

Il numero totale di definizioni di segmenti qualificati viene ricavato dal processo di segmentazione giornaliero, che include i tipi di pubblico idonei per le definizioni di segmenti in batch e in streaming. Questo valore viene visualizzato sia per le definizioni dei segmenti batch che per quelle dei segmenti in streaming.

Il numero in "Ultimi X giorni" solo include tipi di pubblico qualificati nella segmentazione in streaming e solo aumenta se i dati sono stati inviati in streaming al sistema e conta per tale definizione di streaming. Questo valore è only visualizzato per le definizioni dei segmenti di streaming. Di conseguenza, questo valore maggio viene visualizzato come 0 per le definizioni dei segmenti batch.

Di conseguenza, se noti che il numero in "Ultimi X giorni" è zero e anche il grafico a linee riporta zero, hai non inviato in streaming nel sistema tutti i profili che sarebbero idonei per la definizione del segmento.

Quanto tempo ci vuole affinché una definizione di segmento sia disponibile?

È necessaria fino a un’ora perché la definizione di un segmento sia disponibile.

Ci sono limiti ai dati inviati in streaming?

Affinché i dati in streaming possano essere utilizzati nella segmentazione in streaming, deve essere presente una spaziatura tra gli eventi in streaming. Se un numero eccessivo di eventi viene inviato in streaming nello stesso secondo, Platform tratterà tali eventi come dati generati da bot, che verranno eliminati. Come best practice, è necessario disporre di almeno cinque secondi tra i dati dell'evento per garantire che vengano utilizzati correttamente.