LEVEL 1: PURCHASE - INDIVIDUALIZE

The newsletter integration matches the LEVEL 1 TPO: PURCHASE - INDIVIDUALIZE

The Individualize TPO consists in the integration of product recommendations on the e-mail (or other outbound messages) sent to the user.

A light-weight integration with our Composite Image / Redirection link Web-Service can be used which doesn’t require any integration of Boxalino Narrative API and only require the integration of special dynamic links in your e-mail templates: <a href=“LINK”><img src=“LINK”/></a>.

Refer to our related documentation if you want to implement this light-weight integration.

The specialties of the Individualize integration are the following:

As you will request product recommendations for many different clients to be sent in E-mail, you need to make Batch requests grouping many (typically 500 - 1000 requests in one batch)
You should not use “main.bx-cloud.com” but “track.bx-cloud.com” as the main clouds should not receive heavy loads of requests at a specific moment which might affect the average request time performances!

Description

The Narrative API is to be used in order to generate dynamic newsletter content, personalized for each of your subscribers.

For a base integration, the API response is in the format of recommended content IDs (products, blogs, etc) for each of the customers . Based on the received IDs - your own system can load content to generate the template of the newsletter.

In the API request, it is possible to access the index data for your content with the use of the returnFields in the JSON request.

The structure of your Newsletter response is defined in Boxalino Intelligence Admin https://intelligence.bx-cloud.com/ in the Narratives menu.

API Endpoint

As described in the documentation :

for test, connect to https://r-st.bx-cloud.com/narrative/<account-name>/api/1?profileId=<first-customer-in-batch>
for production release, please connect to https://track.bx-cloud.com/narrative/<account-name>/api/1?profileId=<first-customer-in-batch>

Request Headers

The request has the following requirements:

'POST' request
'Content-Type' => 'application/json'

Testing the API requests

Because it is an API, it is possible to test the API requests used by your integration with the help of Postman or Advanced Rest Client (from Chrome) https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related

API integration

The Individualize TPO consists in the integration of product recommendations on the e-mail (or other outbound messages) sent to the user.

BATCH REQUEST

{
  //...
  "batch": [
    {
      "customerId":"1234",
      "parameters": {
        "campaign": ["myCampaignA"]
      }
    },
    {
      "customerId":"4567",
      "parameters": {
        "campaign": ["myCampaignB"]
      }
    }
  ]
}

Name

Example value

Description

batch

the list of customer requests to be processed all in one call

customerId

1234

the customer Id

parameters

{“campaign”:[“myCampaign”]}

configured parameters, optional, needed for parameters specific to each customer.

Global parameters which should apply to all customers can be provided as normal.

do not have any automatic effect but might be require for specific configuration (for example: to indicate the current campaign which will help the system identify what are the best matches related to this campaign).

BATCH RESPONSE

Instead of the standard Response JSON structure as described in the documentation:

{
  "blocks": [
    {
      "blocks": []
    },
    {
      "blocks": [
        {
          "blocks": []
        }
      ]
    }
  ]
}

The Batch request provide a difference structure:

[
  {
    "customerId": 134,
    "blocks": [
      {
        "blocks": []
      },
      {
        "blocks": [
          {
            "blocks": []
          }
        ]
      }
    ]
  }
]

So, instead of one object with a “blocks” parameter, the response is a list of objects each having a “customerId” parameter in addition to the “blocks” parameter.

The inner Structure of the “blocks” parameters is unchanged.

Sample API Request

**insert your setup`s credentials.

{
  "username": "",
  "apiKey": "",
  "apiSecret": "",
  "batch": [
    {
      "customerId": "3"
    },
    {
      "customerId": "2"
    }
  ],
  "widget": "newsletter",
  "dev": false,
  "test": false,
  "hitCount": 4,
  "offset": 0,
  "language": "de",
  "groupBy": "products_group_id",
  "returnFields": [
    "title",
    "standardPrice",
    "discountedPrice",
    "products_cache_image_url"
  ], 
  "parameters": [
    {
      "campaign": "ABC"
    }
  ]
}

Newsletter Integration