Edge segmentation
Edge segmentation is the ability to evaluate segment definitions in Adobe Experience Platform instantaneously on the edge, enabling same page and next page personalization use cases.
Getting started
This developer guide requires a working understanding of the various Adobe Experience Platform services involved with edge segmentation. Before beginning this tutorial, please review the documentation for the following services:
- Real-Time Customer Profile: Provides a unified consumer profile in real-time, based on aggregated data from multiple sources.
- Adobe Experience Platform Segmentation Service: Allows you to build audiences from Real-Time Customer Profile data.
- Experience Data Model (XDM): The standardized framework by which Platform organizes customer experience data.
In order to successfully make calls to any Experience Platform API endpoints, please read the guide on getting started with Platform APIs to learn about required headers and how to read sample API calls.
Edge segmentation query types query-types
In order for a segment to be evaluated using edge segmentation, the query must conform to the following guidelines:
chain(xEvent, timestamp, [A: WHAT(eventType = "addToCart")])
homeAddress.countryCode = "US"
homeAddress.countryCode = "US" and chain(xEvent, timestamp, [A: WHAT(eventType = "addToCart")])
not(chain(xEvent, timestamp, [A: WHAT(eventType = "homePageView")]))
chain(xEvent, timestamp, [X: WHAT(eventType = "addToCart") WHEN(< 24 hours before now)])
homeAddress.countryCode = "US" and chain(xEvent, timestamp, [X: WHAT(eventType = "addToCart") WHEN(< 24 hours before now)])
homeAddress.countryCode = "US" and not(chain(xEvent, timestamp, [X: WHAT(eventType = "addToCart") WHEN(< 24 hours before now)]))
chain(xEvent, timestamp, [A: WHAT(eventType = "homePageView") WHEN(< 24 hours before now) COUNT(5) ] )
homeAddress.countryCode = "US" and chain(xEvent, timestamp, [A: WHAT(eventType = "homePageView") WHEN(< 24 hours before now) COUNT(5) ] )
not(chain(xEvent, timestamp, [A: WHAT(eventType = "homePageView") WHEN(< 24 hours before now) COUNT(5) ] ))
chain(xEvent, timestamp, [X: WHAT(eventType = "homePageView") WHEN(< 24 hours before now)]) and chain(xEvent, timestamp, [X: WHAT(eventType = "checkoutPageView") WHEN(< 24 hours before now)])
homeAddress.countryCode = "US" and chain(xEvent, timestamp, [X: WHAT(eventType = "homePageView") WHEN(< 24 hours before now)]) and chain(xEvent, timestamp, [X: WHAT(eventType = "checkoutPageView") WHEN(< 24 hours before now)])
homeAddress.countryCode = "US" and inSegment("existing segment")
chain(xEvent, timestamp, [A: WHAT(eventType = "addToCart") WHERE(externalSegmentMapProperty.values().exists(stringProperty="active"))])
Additionally, the segment must be tied to a merge policy that is active on edge. For more information about merge policies, please read the merge policies guide.
A segment definition will not be enabled for edge segmentation in the following scenarios:
- The segment definition includes a combination of a single event and an
inSegment
event.- However, if the segment contained in the
inSegment
event is profile only, the segment definition will be enabled for edge segmentation.
- However, if the segment contained in the
Retrieve all segments enabled for edge segmentation
You can retrieve a list of all segments that are enabled for edge segmentation within your organization by making a GET request to the /segment/definitions
endpoint.
API format
To retrieve segments enabled for edge segmentation, you must include the query parameter evaluationInfo.synchronous.enabled=true
in the request path.
GET /segment/definitions?evaluationInfo.synchronous.enabled=true
Request
curl -X GET \
'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.synchronous.enabled=true' \
-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}'
Response
A successful response returns an array of segments in your organization that are enabled for edge segmentation. More detailed information about the segment definition returned can be found in the segment definitions endpoint guide.
{
"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": false
},
"synchronous": {
"enabled": true
}
},
"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": false
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": true
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"sortField": "creationTime",
"sort": "desc",
"pageSize": 2,
"limit": 100
},
"link": {}
}
Create a segment that is enabled for edge segmentation
You can create a segment that is enabled for edge segmentation by making a POST request to the /segment/definitions
endpoint that matches one of the edge segmentation query types listed above.
API format
POST /segment/definitions
Request
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": false
},
"synchronous": {
"enabled": true
}
}
}'
Response
A successful response returns the details of the newly created segment definition that is enabled for edge segmentation.
{
"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": "chain(xEvent, timestamp, [X: WHAT(var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = "true")])"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": true
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
Next steps
Now that you know how to create edge-segmentation-enabled segments, you can use them to enable same-page and next-page personalization use cases.
To learn how to perform similar actions and work with segments using the Adobe Experience Platform user interface, please visit the Segment Builder user guide.
Appendix
The following section lists frequently asked questions regarding edge segmentation:
How long does it take for a segment to be available on the Edge Network?
It takes up to one hour for a segment to be available on the Edge Network.