Utvärdera händelser i nära realtid med strömmande segmentering

Med direktuppspelningssegmentering på Adobe Experience Platform kan kunderna segmentera i nära realtid samtidigt som de fokuserar på datarikedom. Med direktuppspelningssegmentering sker nu segmentkvalificeringen när direktuppspelningsdata når Platform, vilket minskar behovet av att schemalägga och köra segmenteringsjobb. Med den här funktionen kan de flesta segmentregler utvärderas när data skickas till Platform, vilket innebär att segmentmedlemskapet hålls uppdaterat utan att schemalagda segmenteringsjobb körs.

Komma igång

Den här utvecklarhandboken kräver en fungerande förståelse av de olika Adobe Experience Platform-tjänsterna som är involverade i direktuppspelningssegmentering. Innan du börjar med den här självstudiekursen bör du läsa dokumentationen för följande tjänster:

I följande avsnitt finns ytterligare information som du behöver känna till för att kunna anropa Platform API:er.

Läser exempel-API-anrop

Utvecklarhandboken innehåller exempel på API-anrop som visar hur du formaterar dina begäranden. Det kan vara sökvägar, obligatoriska rubriker och korrekt formaterade begärandenyttolaster. Ett exempel på JSON som returneras i API-svar finns också. Information om de konventioner som används i dokumentationen för exempel-API-anrop finns i avsnittet Så här läser du exempel-API-anrop i felsökningsguiden för Experience Platform.

Samla in värden för obligatoriska rubriker

För att kunna anropa Platform API:er måste du först slutföra autentiseringssjälvstudiekursen. När du slutför självstudiekursen för autentisering visas värdena för var och en av de obligatoriska rubrikerna i alla Experience Platform API-anrop, vilket visas nedan:

Alla resurser i Experience Platform är isolerade till specifika virtuella sandlådor. Alla begäranden till Platform API:er kräver en rubrik som anger namnet på sandlådan som åtgärden ska utföras i:

Alla begäranden som innehåller en nyttolast (POST, PUT, PATCH) kräver ytterligare en rubrik:

Ytterligare rubriker kan behövas för att slutföra specifika begäranden. De rätta rubrikerna visas i vart och ett av exemplen i det här dokumentet. Var särskilt uppmärksam på exempelbegäranden för att se till att alla obligatoriska rubriker inkluderas.

Strömmande segmenteringsaktiverade frågetyper query-types

För att en segmentdefinition ska kunna utvärderas med hjälp av direktuppspelningssegmentering måste frågan följa följande riktlinjer.

En segmentdefinition kommer inte att aktiveras för direktuppspelningssegmentering i följande scenarier:

Observera att följande riktlinjer gäller vid direktuppspelningssegmentering:

Om en segmentdefinition ändras så att den inte längre uppfyller villkoren för direktuppspelningssegmentering, kommer segmentdefinitionen automatiskt att växla från"direktuppspelning" till"Gruppering".

Dessutom sker okvalificerat segment, på samma sätt som segmentkvalificering, i realtid. Om en profil inte längre kvalificerar sig för en segmentdefinition blir den därför omedelbart okvalificerad. Om segmentdefinitionen till exempel frågar efter"Alla användare som har köpt röda skor de senaste tre timmarna", efter tre timmar, kommer alla profiler som ursprungligen kvalificerades för segmentdefinitionen att vara okvalificerade.

Hämta alla segmentdefinitioner aktiverade för direktuppspelningssegmentering

Du kan hämta en lista över alla segmentdefinitioner som har aktiverats för direktuppspelningssegmentering inom organisationen genom att göra en GET-förfrågan till slutpunkten /segment/definitions.

API-format

Om du vill hämta definitioner för direktuppspelningsaktiverade segment måste du ta med frågeparametern evaluationInfo.continuous.enabled=true i sökvägen för begäran.

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

Begäran

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}'

Svar

Ett lyckat svar returnerar en array med segmentdefinitioner i organisationen som är aktiverade för direktuppspelningssegmentering.

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "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"
            },
            "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": {}
}

Skapa en segmentdefinition som kan direktuppspelas

En segmentdefinition aktiveras automatiskt för direktuppspelning om den matchar någon av de typer av direktuppspelningssegmentering som listas ovan.

API-format

POST /segment/definitions

Begäran

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"
    },
    "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
        }
    }
}'

Svar

Ett lyckat svar returnerar information om den nyligen skapade segmentdefinitionen som är aktiverad för direktuppspelning.

{
    "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "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
}

Aktivera schemalagd utvärdering enable-scheduled-segmentation

När utvärderingen av direktuppspelning har aktiverats måste en baslinje skapas (efter vilken segmentdefinitionen alltid är aktuell). Schemalagd utvärdering (även kallad schemalagd segmentering) måste först aktiveras för att systemet automatiskt ska kunna utföra baselering. Med schemalagd segmentering kan organisationen följa ett återkommande schema för att automatiskt köra exportjobb för att utvärdera segmentdefinitioner.

Skapa ett schema

Genom att göra en schemaförfrågan till slutpunkten /config/schedules kan du skapa ett schema och inkludera den POST då schemat ska utlösas.

API-format

POST /config/schedules

Begäran

Följande begäran skapar ett nytt schema baserat på specifikationerna i nyttolasten.

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"
        }'

Svar

Ett lyckat svar returnerar information om det nya schemat.

{
    "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
}

Aktivera ett schema

Som standard är ett schema inaktivt när det skapas, såvida inte egenskapen state är inställd på active i texten för skapandebegäran (POST). Du kan aktivera ett schema (ange state till active) genom att göra en PATCH-begäran till /config/schedules-slutpunkten och inkludera ID:t för schemat i sökvägen.

API-format

POST /config/schedules/{SCHEDULE_ID}

Begäran

Följande begäran använder JSON Patch-formatering för att uppdatera state för schemat till 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"
        }
      ]'

Svar

En lyckad uppdatering returnerar en tom svarstext och HTTP-status 2004 (inget innehåll).

Samma åtgärd kan användas för att inaktivera ett schema genom att ersätta värdet i föregående begäran med inaktivt.

Nästa steg

Nu när du har aktiverat både nya och befintliga segmentdefinitioner för direktuppspelningssegmentering och aktiverat schemalagd segmentering för att utveckla en baslinje och utföra återkommande utvärderingar, kan du börja skapa segmentdefinitioner som är aktiverade för din organisation.

Om du vill lära dig hur du utför liknande åtgärder och arbetar med segmentdefinitioner med Adobe Experience Platform användargränssnitt kan du gå till användarhandboken för Segment Builder.

Bilaga

I följande avsnitt visas vanliga frågor om direktuppspelningssegmentering:

Händer direktuppspelad segmentering"utan kvalificering" också i realtid?

I de flesta fall sker icke-kvalificering av direktuppspelad segmentering i realtid. Däremot är definitioner för direktuppspelningssegment som använder segment av segment inte okvalificerade i realtid, utan efter 24 timmar.

Vilka data fungerar direktuppspelningssegmentering på?

Direktuppspelningssegmentering fungerar på alla data som har importerats från en direktuppspelningskälla. Segment som importerats med hjälp av en batchbaserad källa utvärderas nightly, även om det kvalificerar för direktuppspelningssegmentering. Händelser som direktuppspelas i systemet med en tidsstämpel som är äldre än 24 timmar kommer att bearbetas i det efterföljande batchjobbet.

Hur definieras segmentdefinitioner som grupp- eller direktuppspelningssegmentering?

En segmentdefinition definieras som antingen batch- eller direktuppspelningssegmentering baserat på en kombination av frågetyp och händelsehistorikens varaktighet. En lista över vilka segmentdefinitioner som ska utvärderas som ett direktuppspelningssegment finns i avsnittet frågetyper för direktuppspelningssegmentering.

Observera att om ett segment innehåller både och inSegment uttryck och en direkt enkel händelsekedja, kan det inte kvalificera sig för direktuppspelningssegmentering. Om du vill att den här segmentdefinitionen ska vara giltig för direktuppspelningssegmentering, bör du göra den direkta single-event-kedjan till en egen segmentdefinition.

Varför fortsätter antalet"totala kvalificerade" segmentdefinitioner att öka medan antalet under"De senaste X dagarna" är noll i avsnittet med segmentdefinitionsdetaljer?

Antalet totala kvalificerade segmentdefinitioner hämtas från det dagliga segmenteringsjobbet, som omfattar målgrupper som är kvalificerade för både batch- och direktuppspelningssegmentdefinitioner. Det här värdet visas för både gruppsegmentsdefinitioner och segmentdefinitioner för direktuppspelning.

Talet under de senaste X dagarna endast innehåller målgrupper som är kvalificerade för direktuppspelningssegmentering, och endast ökar om du har direktuppspelade data i systemet och det räknas mot den direktuppspelningsdefinitionen. Det här värdet visas endast för definitioner av direktuppspelade segment. Därför kan det här värdet ​ ​visas som 0 för gruppsegmentsdefinitioner.

Om du ser att talet under"De senaste X dagarna" är noll och linjediagrammet också visar noll, har du inte direktuppspelat några profiler i systemet som skulle vara kvalificerade för den segmentdefinitionen.

Hur lång tid tar det innan en segmentdefinition är tillgänglig?

Det tar upp till en timme innan en segmentdefinition är tillgänglig.

Finns det några begränsningar för de data som strömmas in?

För att direktuppspelade data ska kunna användas vid direktuppspelningssegmentering måste det finnas ett mellanrum mellan de direktuppspelade händelserna. Om för många händelser direktuppspelas inom samma sekund kommer Platform att behandla dessa händelser som robotgenererade data och de kommer att ignoreras. Som bästa praxis bör du ha minst fem sekunder mellan händelsedata för att säkerställa att data används på rätt sätt.