This feature is currently in BETA version.

Please mind that full and exact URL of the managed endpoint can be found in the Managed endpoint UI! The format is:

POST https://<api-domain>/webxp/s/<project-id>/managed-endpoints/<managed-endpoint-id>

Managed endpoints return personalized HTTP responses in a format defined by you and so suit your needs the best.

Personalization

When setting up the managed endpoints in the Engagement application, you can use HTTP clients in the language of your choice for calling the endpoint and you can also define the response in the format you want.
They return the rendered templates fully customizable by you using Jinja. All standard web personalization accessors are available such as customer properties, attributes, recommendations, etc. (those accessors are similar to the ones available in weblayers).

👍

Tip!

We recommend creating small and targeted endpoints to get better personalized data.

Bear in mind that managed endpoints add their own metadata into available Jinja variables. See the example in the table below:

Managed endpoint metadata

Meaning

managed_endpoint.id

ID of the managed endpoint

managed_endpoint.name

Name of the managed endpoint

managed_endpoint.variant.id

ID of the selected variant when using A/B testing

managed_endpoint.variant.name

Name of the selected variant when using A/B testing

Security

You can access the managed endpoints only via authentication to provide better security. The feature supports all of our standard API authentication groups - public and private. However, you have to assign the specific API group to the specific managed endpoint first by setting it up in your API settings. The reason for it is that only keys that belong to the configured API groups can be used for authenticated managed endpoint HTTP calls.

📘

Tip

We recommend using the Private API group for managed endpoints that can expose private customer data.

It is advised to use the public API groups only when calling managed endpoints from customers´ devices - web browsers and mobile apps.

Calling Managed endpoints using HTTP

request body

In the request body, the authentication is excluded by default so you will have to set up the authentication header additionally. Please refer to this guide to set it up correctly.

🚧

Maximum API request size

Maximum API request size (params in payload) is 10kB.

If the API request payload exceeds the maximum size, the API will reject the request and you will get the response with HTTP 413 status code.

POST https://<api-domain>/webxp/s/<project-id>/managed-endpoints/<managed-endpoint-id>

Full and exact URL of the managed endpoint can be found in the Managed endpoint UI.

Format of expected request body

{
  "customer_ids": {
    "<id-name>": "<id-value>"
  },
  "params": {}
}

🚧

The "customer_ids" field is required and must contain at least one valid customer ID. The params field is optional. However, if it is specified, it must be a JSON object (see the Request parameters section).

Example of the request with specific values:

{
  "customer_ids": {
    "registered": "my-customer-1"
  },
  "params": {
    "item_id": 123,
    "item_category": "socks"
  }
}

response

The managed endpoint returns either a successful or unsuccessful HTTP status code. If it returns HTTP 200 OK status code, it is a success and the body will then render the Jinja template that you have configured for that specific managed endpoint.

The API also sets "Content-Type" HTTP response header to one of these values, depending on what you have configured: application/json, application/xml, text/plain.

🚧

Content-type header does not support HTML due to security reasons. It only supports JSON, XML and TEXT.

The possible unsuccessful HTTP statuses codes are:

HTTP status code

Its meaning

400

Invalid request body (for example missing customer IDs, malformed JSON) or an error in the Jinja template code defined by the user.

401

Missing or invalid API key.

403

API key does not have permission to access this specific Managed endpoint.

413

Request payload size exceeds 10kB.

502, 503

Server errors, usually mean that some service is overloaded.

Apart from status codes, the possible endpoint statuses are:

  • Exposed / Started - Managed endpoint is active and responds to API requests
  • Save / not Exposed (Stopped) - Managed endpoint can be edited, but is not available for API requests (returns HTTP 404 status code)

Request parameters

The Managed endpoint API accepts a params object. This object will be parsed and then passed into the Managed endpoint Jinja code, where it is available as the params variable.

This allows request-specific information to be used in the Jinja template code. For example, you could set up the request recommendations from the currently visiting category by passing the category inside the request parameters and then using the category to call the recommendations Jinja accessor.

Request example:

{
  "params": {
    "current_category": "shirts"
  }
}

Example of using the parameter in the Jinja template to recommend items from the current category:

{% set recommendations_filter = [] %}
{% if params.current_category %}
  {% set recommendations_filter = [{"property": "category", "constraint": {"type":"string","operator":"equals","operands":[params.current_category]}}] %}
{% endif %}
recommendations("engine-id", catalog_filter=recommendations_filter)

PII data

Only those users that have the Personal Data Viewer role (or flag), can be exposed to endpoints containing PII data. Please mind that it currently works only for private customer properties, not attributes using private properties!

Below is the list of actions you can do as the Personal Data Viewer if the managed endpoint template contains private customer properties:

  • starting Managed endpoint,
  • editing the running Managed endpoint in case the new version uses private customer properties

A/B Testing

You can use A/B testing on managed endpoints as well to provide different responses to different groups of customers. When A/B testing is turned on, default responses for the Control group are required. It will be set to an empty response by default but you can change it.

🚧

It is important that you set up the Control group if you want to have personalized responses. Otherwise, the Managed endpoints will return HTTP 200 with an empty response.

Once you have successfully run the A/B test, that has found your winning variant, and want to turn it fully on, please make sure you copy/paste the winning variant code into the first variant and turn off A/B testing in the A/B test tab. We recommend not changing the distribution of the already running A/B test, e.g. if you start with a 50/50 split, you should not change the split to 70/30 or 100/0 later on, as this can cause issues with persistent variants of returning customers.

📘

Note

If you wish to track your own Managed endpoint "show" event for a more accurate A/B test evaluation, you can access the managed_endpoint.variant.id variable in the Jinja template to get the selected variant ID.

New access roles

Role

Permitted actions

Managed Endpoints Viewer

Can view managed endpoints.

Managed Endpoints Editor

Can view and edit Managed endpoints. Please note that editing a running endpoint requires the Publisher role.

Managed Endpoints Publisher

Can view, edit, and publish (expose/ unexpose) Managed endpoints.

Language
Click Try It! to start a request and see the response here!