Versions Compared

Old Version 2

changes.mady.by.user Dana Negrescu

Saved on

compared with

New Version Current

changes.mady.by.user Dana Negrescu

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Getting started

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

  1. Create newsletter images for your products, banners, blog articles, etc

  2. Provide Boxalino recommendations for newsletter (products, blog articles, etc)

  3. 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:

  1. an FTP/sFTP server where the generated images are stored (username, password and path to ex

  2. a HTML+CSS template for the images

Once these are provided, the integration can continue.

Info

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.

Info

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.

...

Widget

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.

  1. Go to Deployment → Testing

  2. Select the widget used for the trigger (ex: newsletter);

  3. In the Widget view/tab,set the language, live mode with live data

  4. In the Parameters tab pre-define your product filters (if any*) (ex: product_status=1, etc)

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

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

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

Code Block
languagehtml
<!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>

...

Code Block
languagejs
<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

Info

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 Removed

Image creation

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

  1. Go to Advanced → 3rd Party Push. Click on + Add button on top-left corner.

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

    Image Removed

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

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

      Code Block
      languagejson
      {
  "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
}

  4. In the HTML Source tab, in the dropdown, select the template.html created in the prior step.

  5. Click on Save. Close the window and then click on Test button above.

Testing Template

...

...

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

Image Removed

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.

Info

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

  1. Edit and Save the Template

  2. Test >> Config

  3. 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:

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

  2. 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:

Code Block
breakoutModewide
languagehtml
<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:

...

Getting started

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

  1. Create newsletter images for your products, banners, blog articles, etc

  2. Provide Boxalino recommendations for newsletter (products, blog articles, etc)

  3. 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:

  1. an FTP/sFTP server where the generated images are stored (username, password and path to export)

  2. a HTML + CSS template for the images

Once these are provided, the integration can continue.

Info

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

Info

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 dedicated widget / WPO is used to configure your optimization rules.

In Boxalino Intelligence Admin , in 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 CloudConvertto generate the images defined in your template. CloudConvert exports the images to your (s)FTP server.

Widget / WPO

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.

  1. Go to Deployment → Testing

  2. Select the widget used for the trigger (ex: newsletter);

  3. In the Widget view/tab,set the language, live mode with live data

  4. In the Parameters tab pre-define your product filters (if any*) (ex: product_status=1, etc)

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

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

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

Info

Optionally, you can ask Boxalino to assist with the WPO / 3rd party push step.

Template

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

  2. Copy paste your HTML template.

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

    Code Block
    languagehtml
    <!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 per your template 
  </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>

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

    Code Block
    languagejs
    <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');
      
      /** set the path for "placeholder" product image to be used **/
      if(values.products_image.length==0){values.products_image[0]="placeholder/default/default.jpg";}
      /** if the synced product image is not the full path, replace the <public path> with link to your e-shop where the product images are stored **/
      $('#bx-image').attr("src", <public path> + 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>

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

Info

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 Added

Image creation

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

  1. Go to Advanced → 3rd Party Push. Click on + Add button on top-left corner.

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

    1. we recommend to use the id , title and discountedPrice as cache key (the products_image and products_group_id are not required)

      Image Added

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

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

      Code Block
      languagejson
      {
  "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
}

  4. In the HTML Source tab, in the dropdown, select the template.html created in the prior step.

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

Image Added

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.

Info

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

  1. Edit and Save the Template

  2. Test >> Config

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

You can review the Newsletter Integration in this section Newsletter Image & Redirect URLs

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

...

  1. You can set a campaign title;

  2. The campaign must have the Status checkbox selected (it will mark it as an active campaign)

  3. If you also check the Promoted checkbox - the JSSOR banner CONTENT attached to the campaign (if any) - will can appear in your e-shop recommendations as well (ex: banner sliders).

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

  5. The CUID field is used to link your newsletter campaign from your system (mailchimp, emarsys) to the product rules from the Target section.

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

  7. Once all the filters are set - your campaign rules are defined. Click on Save and the view will close.

  8. In order to enable the campaign, click on Push Data button in your Campaigns menu.

There is a 20-25min process following the “Push Data” event which will update the campaign correlations in our real-time service.

Info

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.

...