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>

To achieve the vision of true omnichannel personalization with superior customer experience, Managed Endpoints (also known as server-side rendering or server-side personalization) offers the flexibility to leverage customer data within Bloomreach Engagement to personalize any customer touchpoint, while maintaining fast load times, better page performance and higher security.

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

Why we developed this feature

Customers need their experiences to be personalized and tailored uniquely for them. That is because personalization has a significant impact on order value, purchase frequency, overall revenue, and customer loyalty.

However, mere pre-built channels and templates, scheduled exports, rigid APIs, or webhooks to retrieve data can be limiting. We developed the Managed Endpoints API so that you can get back a personalized response in a format defined by you to truly personalize the customer experience on any third-party application or channel. Thus, the benefits of this feature include flexibility as well as enhanced security, and higher speed to run advanced use cases.

How it works

Personalization

Managed endpoints return rendered templates that you can fully customize. Anything that is defined in the template can be retrieved in an HTTP response when the endpoint is called from a third party. 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 using Jinja (we support 3 different content type headers - JSON, XML, and text).

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 metadataMeaning
managed_endpoint.idID of the managed endpoint
managed_endpoint.nameName of the managed endpoint
managed_endpoint.variant.idID of the selected variant when using A/B testing
managed_endpoint.variant.nameName 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.

How to set up Managed endpoints

Go to Data & Assets > Managed endpoints. In the top-right corner, click on '+Create new'.

678678

Consequently, write your endpoint response definition code as text, XML, or JSON into the editor that will be displayed. For personalized content, use Jinja.

The example below displays a JSON that will render the first name of the customer using the API. Then you need to Save and Start your Managed endpoint which will create a pop-up with an URL address where the endpoint runs.

This URL is called POST request, rendering the responses that you specified earlier. So in the case of the example below, a JSON with the first name.

16841684

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 codeIts meaning
400Invalid request body (for example missing customer IDs, malformed JSON) or an error in the Jinja template code defined by the user.
401Missing or invalid API key.
403API key does not have permission to access this specific Managed endpoint.
413Request payload size exceeds 10kB.
502, 503Server 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 also use A/B testing on managed endpoints 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 essential that you set up a 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

RolePermitted actions
Managed Endpoints ViewerCan view managed endpoints.
Managed Endpoints EditorCan view and edit Managed endpoints. Please note that editing a running endpoint requires the Publisher role.
Managed Endpoints PublisherCan view, edit, and publish (expose/ unexpose) Managed endpoints.
Language
Click Try It! to start a request and see the response here!