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

Senaste uppdatering: 2023-08-18
  • Ämnen:
  • Segments
    Visa mer om det här ämnet
  • Skapat för:
  • Developer
    User
    Admin
    Leader
OBSERVERA

I följande dokument beskrivs hur du använder direktuppspelningssegmentering med API:t. Mer information om hur du använder direktuppspelningssegmentering med användargränssnittet finns i gränssnittsguide för strömningssegmentering.

Direktuppspelningssegmentering på Adobe Experience Platform gör det möjligt för kunderna att segmentera i nära realtid samtidigt som de fokuserar på datamöjligheter. Med direktuppspelningssegmentering sker nu segmentkvalificeringen i takt med att data strömmas in i 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.

OBSERVERA

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.

Dessutom kan segmentdefinitioner som utvärderas med direktuppspelningssegmentering avvika mellan det ideala och det faktiska medlemskapet om segmentdefinitionen baseras på en annan segmentdefinition som utvärderas med gruppsegmentering. Om till exempel segment A är baserat på segment B och segment B utvärderas med gruppsegmentering, eftersom segment B bara uppdateras var 24:e timme, kommer segment A att flyttas längre bort från de faktiska data tills det synkroniseras om med segmentet B.

Komma igång

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

  • Real-Time Customer Profile: Tillhandahåller en enhetlig konsumentprofil i realtid baserat på aggregerade data från flera källor.
  • Segmentation: Ger möjlighet att skapa målgrupper med segmentdefinitioner och andra externa källor från Real-Time Customer Profile data.
  • Experience Data Model (XDM): Det standardiserade ramverk som Platform organiserar kundupplevelsedata.

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

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 konventionerna som används i dokumentationen för exempel-API-anrop finns i avsnittet om läsa exempel-API-anrop i Experience Platform felsökningsguide.

Samla in värden för obligatoriska rubriker

För att ringa Platform API:er måste du först slutföra självstudiekurs om autentisering. När du är klar med självstudiekursen för autentisering visas värdena för var och en av de obligatoriska rubrikerna i alla Experience Platform API-anrop enligt nedan:

  • Behörighet: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Alla resurser i Experience Platform isoleras till specifika virtuella sandlådor. Alla förfrågningar till Platform API:er kräver en rubrik som anger namnet på sandlådan som åtgärden ska utföras i:

  • x-sandbox-name: {SANDBOX_NAME}
OBSERVERA

Mer information om sandlådor i Platform, se översiktsdokumentation för sandlåda.

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

  • Content-Type: application/json

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

OBSERVERA

Du måste aktivera schemalagd segmentering för organisationen för att direktuppspelningssegmenteringen ska fungera. Information om att aktivera schemalagd segmentering finns i aktivera segmentering enligt schema

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

Frågetyp Information
En händelse En segmentdefinition som refererar till en enda inkommande händelse utan tidsbegränsning.
En händelse i ett relativt tidsfönster En segmentdefinition som refererar till en enda inkommande händelse.
En händelse med ett tidsfönster En segmentdefinition som refererar till en enda inkommande händelse med ett tidsfönster.
Endast profil En segmentdefinition som bara refererar till ett profilattribut.
En händelse med ett profilattribut inom ett relativt tidsfönster på mindre än 24 timmar En segmentdefinition som refererar till en enda inkommande händelse, med ett eller flera profilattribut, och som inträffar inom ett relativt tidsfönster på mindre än 24 timmar.
Segmentering En segmentdefinition som innehåller en eller flera grupper eller direktuppspelningssegment. Obs! Om ett segment används, diskvalificeras profilen var 24:e timme.
Flera händelser med ett profilattribut En segmentdefinition som refererar till flera händelser inom de senaste 24 timmarna och (valfritt) har ett eller flera profilattribut.

En segmentdefinition not aktiveras för direktuppspelningssegmentering i följande scenarier:

  • Segmentdefinitionen innehåller Adobe Audience Manager (AAM) segment eller egenskaper.
  • Segmentdefinitionen innehåller flera enheter (frågor om flera enheter).
  • Segmentdefinitionen innehåller en kombination av en enda händelse och en inSegment -händelse.
    • Om segmentet i inSegment -händelsen är bara profil, segmentdefinitionen kommer aktiveras för direktuppspelningssegmentering.

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

Frågetyp Riktlinje
Enkel händelsefråga Det finns inga begränsningar för uppslagsfönstret.
Fråga med händelsehistorik
  • Uppslagsfönstret är begränsat till en dag.
  • Ett strikt tidsordningsvillkor måste finns mellan händelserna.
  • Frågor med minst en negerad händelse stöds. Hela händelsen inte vara en negation.

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 är aktiverade för direktuppspelningssegmentering inom organisationen genom att göra en GET-förfrågan till /segment/definitions slutpunkt.

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 till 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"
            },
            "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": {}
}

Skapa en segmentdefinition som kan direktuppspelas

En segmentdefinition aktiveras automatiskt för direktuppspelning om den matchar en av segmenteringstyper för direktuppspelning 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"
    },
    "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
        }
    }
}'
OBSERVERA

Detta är en standardbegäran om att skapa en segmentdefinition. Mer information om hur du skapar en segmentdefinition finns i självstudiekursen om skapa en segmentdefinition.

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

Aktivera schemalagd utvärdering

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.

OBSERVERA

Schemalagd utvärdering kan aktiveras för sandlådor med högst fem (5) sammanfogningsprinciper för XDM Individual Profile. Om din organisation har fler än fem samkörningspolicyer för XDM Individual Profile i en enda sandlådemiljö kommer du inte att kunna använda schemalagd utvärdering.

Skapa ett schema

Genom att göra en POST-förfrågan till /config/schedules kan du skapa ett schema och inkludera den specifika tidpunkt 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"
        }'
Egenskap Beskrivning
name (Obligatoriskt) Schemats namn. Måste vara en sträng.
type (Obligatoriskt) Jobbtypen i strängformat. De typer som stöds är batch_segmentation och export.
properties (Obligatoriskt) Ett objekt som innehåller ytterligare egenskaper som är relaterade till schemat.
properties.segments (Krävs när type är lika med batch_segmentation) Använda ["*"] säkerställer att alla segmentdefinitioner ingår.
schedule (Obligatoriskt) En sträng som innehåller jobbschemat. Jobb kan bara schemaläggas att köras en gång om dagen, vilket innebär att du inte kan schemalägga ett jobb att köras mer än en gång under en 24-timmarsperiod. Exemplet (0 0 1 * * ?) innebär att jobbet utlöses varje dag kl. 1:00:00 UTC. Mer information finns i bilagan cron, uttrycksformat i dokumentationen om scheman inom segmentering.
state (Valfritt) Sträng som innehåller schemats tillstånd. Tillgängliga värden: active och inactive. Standardvärdet är inactive. En organisation kan bara skapa ett schema. Steg för att uppdatera schemat är tillgängliga senare i den här självstudiekursen.

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 state egenskapen ä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 begäran från PATCH till /config/schedules slutpunkten och inklusive ID 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 av 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 veta hur du utför liknande åtgärder och arbetar med segmentdefinitioner med Adobe Experience Platform användargränssnitt går du till Användarhandbok 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. Det gör emellertid definitioner av direktuppspelade segment som använder segment av segment not diskvalificera i realtid, utan att kvalificera sig 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 frågetyper för direktuppspelningssegmentering.

Observera att om ett segment innehåller båda en inSegment -uttryck och en direkt händelsekedja kan den 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.

Numret under de senaste X dagarna endast omfattar målgrupper som är kvalificerade för direktuppspelningssegmentering, och endast ökar om du har direktuppspelade data i systemet och den räknas in i den direktuppspelningsdefinitionen. Det här värdet är endast visas för definitioner av direktuppspelningssegment. Detta resulterar i att detta värde kan visa som 0 för gruppsegmentsdefinitioner.

Om du ser att talet under"De senaste X dagarna" är noll och linjediagrammet också visar noll, har du not strömmade alla profiler till 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.

På denna sida