Getting started

By following this document, you will find out how to:

Create newsletter images for your products, banners, blog articles, etc
Provide Boxalino recommendations for newsletter (products, blog articles, etc)
Create Boxalino campaigns to define the recommendations content-rules

Newsletter images

In order to have your newsletter images created, the client must have the following:

an FTP/sFTP server where the generated images are stored (username, password and path to ex
a HTML+CSS template for the images

Once these are provided, the integration can continue.

For each type of image (banners, blogs, products) that needs to be recommended, a different widget/choice must be created. On a default setup, a widget newsletter is included.

On your FTP path, make sure to use different folders/paths for mobile/desktop views and for each type of content created; the paths` content (ex: /newsletter/products/img1.jpg) must be publicly accessible.

Integration Elements

As mentioned, a widget is to be used to store your optimization rules.

In Boxalino Intelligence Admin , under the Advanced menu, you will locate the Resources tab. This is used to store the custom templates.

In the 3rd Party Push menu, we will design a trigger to generate the images. Boxalino uses CloudConvert to generate the images defined in your template. CloudConvert exports the images to your (s)FTP server.

The widget (newsletter) is used to also fetch the images needed for your conversion. We will have to create a search request using the Testing view.

Go to Deployment → Testing
Select the widget used for the trigger (ex: newsletter);
In the Widget view/tab,set the language, live mode with live data
In the Parameters tab pre-define your product filters (if any*) (ex: product_status=1, etc)
Check that in the Advanced tab the Connection Type:Public (5min cache) is used; also, take note on the grouping field (generally is group id)
Click on Get Results to confirm the products returned and to also see the number of products returned by your widget used for images generation.
Once it`s done, click on the save icon. This will add this search to the list of queries and you can use it for easy testing in the future.

Template

Go to Advanced → Resources; In the view, select the html tab.

Copy paste your HTML template.

For this sample use-case, the template only uses product image, price and title of the product.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
  <meta charset="utf-8">
  <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,600,600i,700,700i,800,800i" rel="stylesheet">
  <style>
     // CSS
  </style>
	
</head>

<script src="https://code.jquery.com/jquery-2.2.4.min.js" crossorigin="anonymous"></script>
  <script>
  // PLACE FOR BOXALINO SCRIPT TO ACCESS PRODUCT INFORMATION
</script>
<body>
	
	<div class="wrapper">
		<div class="product">
			<div class="image">
				<img src="" alt="Product Image" id="bx-image">
			</div>
			<div class="desc">
				<div class="price">
          <div class="price"><span id="bx-old-price"></span></div>
          <span id="bx-price"></span>
				</div>
          <div class="title"><span id="bx-title"></span></div>=
			</div>
		</div>
	</div>
</body>
</html>

Custom Boxalino code: in the <script></script> section of the template provided by you, add the Boxalino javascript request which will feed product information to the template.

<script>
  //default Boxalino API request for product information
  var transport = new Thrift.Protocol(new Thrift.Transport("http://track.bx-cloud.com/p13n.json"));
  client = new P13nServiceClient(transport);
  var args = [];
  args.userRecord = {
    'username': bxProduct.account,
    'apiKey': 'your-account-api-key',
    'apiSecret': 'your-account-api-secret'
  };
  args.inquiries = [{
    //for banners/blogs, please update to a widget that returns the banners/blog content
    'choiceId': 'search', 
    'simpleSearchQuery': {
      'indexId': bxProduct.account,
      'language': bxProduct.language,
      'queryText': '',
      'hitCount': 10,
      //add as many fields as your template requires
      'returnFields': [
        'id', 'discountedPrice', 'standardPrice', 'title', 'products_image' 
      ],
      'groupItemsSortAscending': false,
      'hitsGroupsAsHits': false,
      'filters': [{
        "fieldName": "id", 
        "stringValues": [bxProduct.id]
      }]
    }
  }];

  var choiceReq = new ChoiceRequest(args);
  client.choose(choiceReq, function(res) {
    (function($) {
      var values = res.variants[0].searchResult.hits[0].values;
      //you can inspect the values the JS-way
      //console.log(values);
      var discountedPrice = parseFloat(values.discountedPrice[0]).toFixed(2),
          standardPrice = parseFloat(values.di_listprice[0]).toFixed(2);
      var discount = Math.fround(discountedPrice) < Math.fround(standardPrice);
      var priceElement = $('#bx-price');
      var oldPriceElement = $('#bx-old-price');
      
      if(values.products_image.length==0){values.products_image[0]="placeholder/default/default.jpg";}
      $('#bx-image').attr("src", "https://www.vitaland.ch/media/catalog/product/" + values.products_image[0]);
      $('#bx-title')[0].innerHTML = values.title[0];
      
      priceElement[0].innerHTML = "CHF " + discountedPrice;
      if (discount) {
        oldPriceElement[0].innerHTML = "CHF " + standardPrice;
      }
    })(jQuery);
  });
</script>

Save the template by clicking on the Save button. Once the next step is completed, w

If your store is available in multiple languages, the template will have to be created for each language individually. Use the drop-drown to switch between store languages.

Image creation

Having the widget that returns products/blog articles/banners/etc and the template, we can create the trigger to launch the process.

Go to Advanced → 3rd Party Push. Click on + Add button on top-left corner.
In the opened window, in the General tab select the search request created in the testing view on step1. Configure default fields as cache keys.

In the CloudConvert tab we will set the convert credentials. Some parts are to be left empty, others must be completed by yourself (the SFTP configuration):

startProcessjson:
the screen_width/screen_height attribute is the width/height of the image and should be the same as the width of your <body>-tag in your HTML

{
  "apikey": "LEAVE-EMPTY",
  "inputformat": "website",
  "outputformat": "jpg",
  "input": "url",
  "converteroptions": {
    "screen_width": 340,  //CONFIGURE BASED ON YOUR IMAGE MAX/MIN SIZE
    "screen_height": 550, //CONFIGURE BASED ON YOUR IMAGE MAX/MIN SIZE
    "use_chrome": true,
    "javascript_delay": "2000",
    "quality": 90
  },
  "output": {
    "ftp": {
      "host": "your-ftp-IP-or-HOST",
      "user": "your-ftp-user",
      "path": "your-ftp-server-path-to-store-images",
     "password": "your-ftp-password"
    }
  },
  "wait": false,
  "download": false
}

In the HTML Source tab, in the dropdown, select the template.html created in the prior step.
Click on Save. Close the window and then click on Test button above.

Testing Template

While on the 3rd party trigger menu, click on Actions and then: Test >> Config.

This will save your trigger in our system and publish the configuration in test mode.

Click on Test >> URL

This will open a new blank page with a value <product-id> in the URL.

http://idv1.bx-cloud.com/service-config-view/de/youraccount/yourtriggerid/<product-id>

Replace the <product-id> segment with an actual product ID from your system. You can use the Testing view by selecting your saved request from the drop-down and click on Get Results.

Once replaced the <product-id> with an actual ID of the content returned (product, blog, banner, etc), the template should be rendered.

If it doesn't show the content information then probably there is some mistake in the JavaScript section. You can see if you can solve it by checking the error message in the browser console. If not, you can contact Boxalino for support.

This process is used to test your image template. Every time a change is made in the template, please repeat the steps:

Edit and Save the Template
Test >> Config
Test >> URL.

Testing Image Creation

Once the template testing is done and you are satisfied with how the image looks, you
can click on Test >> Execute.

This will generate 10 images on your FTP server, in the path configured.
Check in your server using your favorite FTP client and open a couple images, to see if the size and content matches your requirements.

Publishing Image Creation

Once the testing phase is over, please run Prod >> Config . Once this is done, get in touch with Boxalino and let us know to automate your image generation once your product data is fully processed.

Newsletter recommendations

Once the images' generation has been automated by Boxalino, the API links can be integrated in your newsletter templates:

image source link : the link to the recommended content`s image on your FTP
https://main.bx-cloud.com/p13n-rest/ img?user=<account-name>&indexId=<account-name>&apiKey=<newsletter-api-key>&profileId=*|CUSTOMERID|*&customerId=*|CUSTOMERID|*&choiceId=newsletter&lang=de&offset=0&rc_campaign=<custom-campaing-code>
content redirect link : the link to redirect the user on click to the content on your e-shop (product, blog, campaign, etc)
https://main.bx-cloud.com/p13n-rest/redirect?user=<account-name>&indexId=<account-name>&apiKey=<newsletter-api-key>&profileId=*|CUSTOMERID|*&customerId=*|CUSTOMERID|*&choiceId=newsletter&lang=de&offset=0&rc_campaign=<custom-campaing-code>

The green data is provided by Boxalino

The red data must be provided by your newsletter engine (the above are Mailchimp variables); the profileId and customerId can not be empty; the value “0” (zero) or “not-set” must be the default configured option in your system

The orange content must be adapted per your strategy (the choice and the offset); the choice is the widget for your content (products, blogs, banners, etc) and the offset is the recommendation element position, starting from 0 (the 1st recommended content for the customer on the campaign)

The blue content are extra-parameters which can be added to your newsletter in order to link them to pre-defined campaigned rules within Boxalino system.

For example, in your recommendation block within your newsletter template, a product recommendation will look like:

<a href="https://main.bx-cloud.com/p13n-rest/
imgRedirect?user=<account-name>&indexId=<account-name>&apiKey=<newsletter-api-key>&profileId=*|CUSTOMERID|*&customerId=*|CUSTOMERID|*&choiceId=newsletter&lang=de&offset=0&rc_campaign=<custom-campaing-code>" target="_blank">
<img src="https://main.bx-cloud.com/p13n-rest/
img?user=<account-name>&indexId=<account-name>&apiKey=<newsletter-api-key>&profileId=*|CUSTOMERID|*&customerId=*|CUSTOMERID|*&choiceId=newsletter&lang=de&offset=0&rc_campaign=<custom-campaing-code>">
</a>

Additionally, if you want to check the image stored on your own servers, you can use the following link with the imgRedirect endpoint:

https://main.bx-cloud.com/p13n-rest/imgRedirect?user=<account-name>&indexId=<account-name>&apiKey=<newsletter-api-key>&profileId=*|CUSTOMERID|*&customerId=*|CUSTOMERID|*&choiceId=newsletter&lang=de&offset=0

Campaign integration

Lets say you are creating campaigns in your newsletter setup (mailchimp, emarsys,etc) and the newsletter should only show certain products. In Boxalino Intelligence you can set-up campaigns with product filters (categories, brands, other filter) which will only target certain product recommendations for the client.

Creating a Boxalino campaign

In Boxalino Intelligence admin go to

Marketing >> Campaigns and click on the +Add button to add a new campaign.

You will be prompt to set a campaign name which has to be unique

Lets look at the campaign modal view opened.

You can set a campaign title;
The campaign must have the Status checkbox selected (it will mark it as an active campaign)
If you also check the Promoted checkbox - the JSSOR banner attached to the campaign (if any) - will appear in your banner sliders.
For the Type there are 2 options:
1. Permanent - without an expiration date, is always active
2. Time-based - only acts within a time frame and will be disabled once it`s finished
The CUID field is used to link your newsletter campaign from your system (mailchimp, emarsys) to the product rules from the Target section.
Use the Target section to set product filters for your campaign (based on the product attributes)
1. if you click on the Search symbol near your field, you can see what filtering options are available
Once all the filters are set - your campaign rules are defined. Click on Save and the view will close.
In order to enable the campaign, click on Push Data button in your Campaigns menu.

The campaigns page comes with a series of tutorials which are being updated by our team. Please check them as well in case your use-case is included.

Widget configuration

In order for your newsletter widget to link your newsletter to the defined campaign to apply targeting rules, a new rule must be added.

Open your widget (ex: newsletter), find the CUID Correlation Promoter and drag it to your strategies list.

Click on

Save&Test and Save for the widget to get updated.

Go to

Deployment >> Publishing and click on Publish all for your changes to apply.

Newsletter links update

To apply the filter to your newsletter link (Boxalino API request), you simply have to append the parameter to the preexisting one (using ‘&’ as a separator). Make sure to add the prefix ‘rc_’ as this will set it as a request context parameter.

If you added the CUID Correlation Promoter rule, your new parameter will be rc_cuid
If you added the Campaign Correlation Promoter rule, your new parameter will be rc_campaign

Update both the img and the imgRedirect link described in the Newsletter Recommendations chapter.

Newsletter Integration