External data component

🚧

Beta

This feature is currently running in Beta-mode and can be activated by Tweakwise. Get in touch with us if you want to know more.

📘

Technical know-how required

Due to the nature of the external data component, you're going to need some technical knowledge to get it up and running. If you need assistance, please contact your Customer Support Manager.

Usages:

• Integrate with an advanced Customer Data Platform that provides highly personalized product recommendations.
• Place sponsored products of specific brands on the top of pages.

The external data component works like all other builder components.

It does not allow you to add _new _products on a fixed position. It will only change the sorting of products that would otherwise be somewhere on a page already, and therefore relevant to your users.

Throughout this guide, we'll be using the same example: we want to push products with the color red because Valentine's Day is coming up.
Note: This specific case is likely not something you'd usually solve with an external data component, but it is one that's easy to grasp.

Example

The screenshot below is from the demoshop. Normally the Pillow, Hoodie & Mug would be placed somewhere further down the page. Using the external data source, they got a more prominent position.

Under the hood, Tweakwise retrieved an ordered list of products from the external source and placed those products on the product grid as configured in the builder.

Data source

The external data component needs to get its data from a data source other than Tweakwise. This is done by sending an HTTP request to an external endpoint/API.

It is then up to the external system to determine the relevant products and send them back to Tweakwise in JSON format. Both GET and POST are supported request methods for making this call to the external system.

Context

For the external system to be able to determine which products are relevant and in what order they should be placed, it is going to need context. Below you can find an overview of all the information Tweakwise can send to your external system.

The information can be passed to the external systems in two different ways: in the URL and in the request body.

URL

One of the ways the information can be sent to your external system is by embedding the information in the URL. When configuring the external data component, you can add parameters in the URL that get replaced by Tweakwise. For example, an external data component with URL https://example.com/{profileKey} will be resolved to https://example.com/test if the profile key used for the frontend API request is test.

📘

Parameters have to be enclosed in curly brackets {}. Supported parameters are profileKey, categoryId and searchTerm. Filters are not supported in the URL.

Body

In addition to using parameters in the URL, if the component is configured to use POST as request method, then we'll send the context to the external system as JSON in the body of the request as well. Below you can find an example of what exactly you can expect to receive.

{
    "cid": 1,
    "profilekey": "profilekey",
    "filters": [
        {
            "type": "The type of filter",
            "attribute": "The name of the attribute",
            "filters": {
                // Nested filters
            }
        }
    ],
    "context": {// only contains data when called from Upselling & cross-selling
      "source": "upsellingCrossSelling",
      "contents": {
        "articleNumber": "X"
      }
    }
}

Format

The external data component needs the data from the external system to be in a specific format. Below you can find the schema the component requires the data to be in.

{
  "items": [
    {
      "id": "10001-116",
      "reference": "VALENTINES-DAY"
    },
    {
      "id": "10001-104",
      "reference": "VALENTINES-DAY"
    },
    // and so on
  ]
}

• id is the product identifier. Usually this is the article number of the product.
• reference can be any text value. See Origin & reference for more information.

The data returned by the external system should always be JSON. External systems may not provide the data exactly as the schema the external data component requires because they're not built specifically with Tweakwise in mind. This is not a problem because the data can be mapped to Tweakwise's format. To facilitate this, external data components have built-in support for JSONata. With JSONata, you can transform the response from the external system to that of the external data component.

Mapping

The product identifier provided by the external system is likely to be the article number of the product. However, it is also possible that it's another unique identifier, like a barcode or EAN. For this reason, it's not possible for Tweakwise to know how to map products in Tweakwise to products received by the external system. To solve this, every external data component has to be linked to an attribute. The values of the attribute are used to find the products the external system is referring to, thereby creating a mapping.

Origin & reference

When the builder, and therefore an external data component, has influenced the sorting of a page, information about the origin of the product gets added to the response. The reference provided by the external system is returned in the response as part of that origin information. With this information you can, for example, keep track of how often a specific promotion was shown or build beacons in your front-end implementation if you choose to send a product session identifier as reference.

{
    "itemno": "10001-116",
    "title": "Tweakwise Pillow Red",
    "price": 11.95,
    "brand": "Tweakwise",
    "image": "https://sttwdocseuwe.blob.core.windows.net/shop/products/kussen-rood.jpg",
    "url": "https://sttwdocseuwe.blob.core.windows.net/shop/products/kussen-rood.jpg",
    "origin": { // The origin object will be left out if the component did not get loaded
        "type": "external-data",
        "name": "Promotion", // The name of the external data component, as configured in the app
        "itemreference": "VALENTINES-DAY" // The reference as provided by the external system
    }
}

Performance

Using an external source will have impact on performance. Certain measures are taken to ensure acceptable performance of the Frontend API:

• If the request (to the external data source) takes longer than 200ms to respond, we'll cancel the request and fall back to the default sorting.
• Our servers are located in Western Europe. It would be preferred to host the external data source in the same region to reduce latency and therefore reduce the impact on performance of the Frontend API.