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) offer 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 you defined that best suits your needs.

🚧

This feature is a part of the Web & App Personalization Package and needs to be enabled by your Customer Success Manager or Account Manager.

Why we developed this feature

Customers need their experiences to be personalized and tailored uniquely to them. Personalization significantly impacts 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 you defined to truly personalize the customer experience on any third-party application or channel. Thus, the benefits of this feature include flexibility, 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 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, such as customer properties, attributes, recommendations, etc. (those accessors are similar to the ones available in weblayers), are available.

👍

Tip!

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

Remember that Managed endpoints add their own metadata to available Jinja variables. See the example in the table below:

Security

To provide better security, you can access the Managed endpoints only via authentication. The feature supports all of our standards API authentication groups —public and private. However, you must first assign the specific API group to the specific Managed endpoint by setting it up in your API settings. Only keys that belong to the configured API groups can be used to authenticate and manage 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.

Remember to allow the API group setting. You must check Managed endpoints under Group permissions > Definitions.

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 uses the API to render the customer's first name. Then, you need to save and Start your Managed endpoint, creating a pop-up with a URL address where the endpoint runs.

This URL is called a POST request, and it renders the responses that you specified earlier. In the example below, it is a JSON with the first name.

Calling Managed endpoints using HTTP

Request body

The authentication is excluded by default in the request body, 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>

The 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 the HTTP 200 OK status code, it is a success, and the body will then render the Jinja template that you configured for that specific Managed endpoint.

The API also sets the "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 status 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)

📘

After calling the Managed endpoint, a new event will be created.

Request parameters

The Managed endpoint API accepts a params object. This object will be parsed and then passed into the Managed endpoint Jinja code, which 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 users with the Personal Data Viewer role (or flag) can be exposed to endpoints containing PII data. Please remember that this 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