Managed Endpoints API

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.

📘

This feature is a part of the Web & App Personalization Package

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:

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.

Compression

Managed endpoints get compressed, along with mobile payloads (In-App Messages, App Inbox).

How to set up Managed endpoints

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

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.

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).

If you use customer_id that doesn't exist in Bloomreach Engagement, it will create a new customer. This allows you to show templates even to new/"non-existent" customers directly from the Managed endpoint.

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:

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