Edge segmentation (beta)

NOTE

The following document states how to perform edge segmentation using the API. For information performing edge segmentation using the UI, please read the edge segmentation UI guide. Additionally, edge segmentation is currently in beta. The documentation and the functionality are subject to change.

Edge segmentation is the ability to evaluate segments 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.
  • Segmentation: Provides the ability to create segments and audiences from your 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 Data Prep 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

In order for a segment to be evaluated using edge segmentation, the query must conform to the following guidelines:

Query type Details
Incoming hit Any segment definition that refers to a single incoming event with no time restriction.
Incoming hit that refers to a profile Any segment definition that refers to a single incoming event, with no time restriction, and one or more profile attributes.
Incoming hit with a time window of 24 hours Any segment definition that refers to a single incoming event within 24 hours
Incoming hit that refers to a profile with a time window of 24 hours Any segment definition that refers to a single incoming event within 24 hours, and one or more profile attributes

The following query types are not currently supported by edge segmentation:

Query type Details
Multiple events If a query contains more than one event, it cannot be evaluated using edge segmentation.
Frequency query Any segment definition that refers to an event happening at least a certain number of times.
Frequency query that refers to a profile Any segment definition that refers to an event happening at least a certain number of times and has one or more profile attributes.

Retrieve all segments enabled for edge segmentation

You can retrieve a list of all segments that are enabled for edge segmentation within your IMS 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: {IMS_ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns an array of segments in your IMS 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": "{IMS_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": "{IMS_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

NOTE

The example below is a standard request to create a segment. For more information about creating a segment definition, please read the tutorial on creating a segment.

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: {IMS_ORG}' \
  -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"
    }
}'

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

On this page