JavaScript

BrainSINS JavaScript integration; suitable for any eCommerce website

Heads up! If your online store is based on Prestashop, you may it easier to use our Prestashop module: Check our Plugins section.

First upload the products feed

As stated in our "Get started" section, BrainSINS needs to get access to your products feed. Our plugins usually produce a products feed in XML format, but if your online store doesn't make use of a standard CMS you need to upload BrainSINS a products feed. For more information, you can check our the documentation page related to the products feed supported by BrainSINS.

An overview

After uploading the products feed, you can continue with our JavaScript integration. As you will see in this guide, our JavaScript integration requires you to include a JavaScript file from our CDN and a set of JavaScript tags based on a custom JSON format, that will inform BrainSINS about your customer's behavior in your online store.

Once we receive your customer's behavior, we are able to analyze that data and interact with your users by means of product recommendations, email retargeting or behavioral targeting; providing a personalized shopping experience to fulfill your customer's desires and your needs as a business owner.

The first step is to include our JavaScript file into everypage of your online store, in the HEAD section:

<!-- BrainSINS Code Starts -->
<script type="text/javascript">
brainsins_token = "TOKEN";
</script>
<script type="text/javascript" async="" src="//d2xkqxdy6ewr93.cloudfront.net/brainsins.js"></script>
<!-- BrainSINS Code Ends -->

The variable TOKEN should be replaced by your unique BrainSINS client ID. You can find that ID accessing our management tool: Settings->Account info. This id has the following structure: BS-0000000000-1.

For instance, if your client code is “BS-1234567890-1″, the could you should generate into the HEAD section would be:

<!-- BrainSINS Code Starts -->
<script type="text/javascript">
brainsins_token = "BS-1234567890-1";
</script>
<script type="text/javascript" async="" src="//d2xkqxdy6ewr93.cloudfront.net/brainsins.js"></script>
<!-- BrainSINS Code Ends -->

In order to send BrainSINS the user's activity, we have developed a JSON format that allows you to send any type of user behavior. Next you will find the full JSON specification, but don't worry if you see too much information, because we only require you to send some information for each type of page in your online store (homepage, product page...).

If you prefer to understand what information pieces need to be implemented in each page type, you can access to our specific guide that shows JSON example for each possible page type in your online store.

BrainSINS JSON Specification

The following code represents our JSON specification. After the code you'll find a brief explanation for each data field.

		
<script type="text/javascript">
var BrainSINSData = {
   pageType: PAGE_TYPE,
   language: LANGUAGE,
   productId: ID_PRODUCT,
   totalAmount: TOTAL,
   categories: CATEGORIES,
   userEmail: EMAIL,
   userNewsletter: WANTS_NEWSLETTER,
   cart: [
      {
         id: ID,
         quantity: QUANTITY
      },
      {
         id: ID,
         quantity: QUANTITY
      },
      ...
   ],
   recommenders: [
      {
         recommenderId: ID,
         location: LOCATION,
         position: POSITION,
         filter: FILTER
      },
      {
         recommenderId: ID,
         location: LOCATION,
         position: POSITION,
         filter: FILTER
      },
      ...	   
   ]
};
</script>

In our JSON data model, we have several data attributes that records the user activity. Next, we will describe each data field, and in what circumstances, page types or desired user behaviors you need to fulfill them.

Data field Page type Description
pagetype all This data field is used to communicate BrainSINS what type of page the user is browsing. You need to replace PAGE_TYPE by one of the following values:

  • product: When the user is browsing a product page.
  • home: When the user is browsing the homepage.
  • category: When the user is browsing a category listing.
  • cart: When the user is at the cart page.
  • checkout: When the user is at the first page of the checkout process. Sometimes this page is the cart page, so in that situation you must use the "checkout" page type.
  • thankYou: When the user has completed the purchase.
  • login: When the user has been redirected to a specific page after the log-in process.
  • logout: When the user has been redirected to a specific page after the log-out process.
As an example, if the user is browing the homepage, this JSON line would contain:

pagetype: "home",
language all If your online storefront manages different languages, you can specify in this field in what language the user is browsing your website. That is needed to show the recommended products details in the proper language. If your have different languages in your online store, you must consider that you need to configure your products feed to send us the information in every language you manage. As an example, imagine that a user is visiting your online store and has chosen to read the contents in Spanish. If you have configured the Spanish language in your catalog using the code "es", you'd need to add the following line to the JSON:

language: "es",
productId product When the user is browsing a product page, the productId field contains the internal id of the product. This id must match the if that you use for that product in the products feed. As an example, if the user is browsing the page for the product with id 676, the JSON code should include:

pagetype: "product",
productId: 676,
totalAmount thankYou When the user finishes a purchase, totalAmount is used to state the final amount for the given purchase. We use this data mainly for analytical purposes. As an example, if the user has finished a purchase of $1,249.32, you should send us that information as a float:

pagetype: "thankYou",
totalAmount: 1249.32,
categories category Categories is used to send BrainSINS a given category or set of categories. Mostly, you'll be needing this field to send the category the user is browsing in a given moment. As an example, if the user is browsing the category listing for shirts in your online store, you'd include the following lines in our JSON:

pagetype: "category",
categories: "shirts",
If the user is not browsing the category listing, you can also include the category field in order to restrain recommendations results according to that category. Although you may learn more about filtering recommendations results in the documentation regarding this topic, you can check the following example to understand how this works. Imagine that you want to show product recommendations in your homepage but you need that the recommended products belong to the categories christmas or holidays. You should include the following code:

pagetype: "home",
categories: "christmas, holidays",
recommenders: [
   {
      recommenderId: 13,
      location: "recommendation-home",
      position: "replace",
      filter: "any"	
   }
],
In the previous example you can learn how to manage several categories (they must be comma separated), and how to filter recommendation results. More about this topic in the section regarding product recommendations.

You must consider that BrainSINS associates categories to the products according to the information you send in your products feed. So you must be consistent in the use of categories.
userEmail any We are able to gather user emails and associate them to browsing sessions, so you can configure eMail retargeting rules to recover abandoned carts, or even send personalized newsletters. When you need to send us a user email because the user has logged-in in your website, or they have introduced their email in a newsletter subscription form, you should include the user's email in this field. Most times, you'll be sending the email in the login page, so the following example is made based on this assumption. But if you want to send us a user email from any other type of page, you only need to add the field userEmail containing the user's email address.

pagetype: "login",
userEmail: "user@domain.com",
userNewsletter any This field is a modifier to userEmail, and must be used only to notify that a given user doesn't want to receive any eMail communications. As an example, if a user with the email address user@domain.com registers at our site but does not want to receive any eMail communication, you should include the following code:

pagetype: "login",
userEmail: "user@domain.com",
userNewsletter: 0,
cart cart The cart field is used to send BrainSINS information about the cart's content of a given user. Mostly you will be using this field when the user is in the cart page, visualizing their cart's content. If a given user has added 1 unit of the product with id=13 and 3 units of the product with id=27, you should include the following code:

pagetype: "cart",
cart: [
   {
      id: 13,
      quantity: 1
   },
   {
      id: 27,
      quantity: 3	
   }
]
This field contains a list of N pairs {id, quantity}, being N the number of different products in the user's cart. Although the main use of this field is expected for the cart page, you can include this field wherever you want to track the carts content of a given user. In some cases, you'd like to synchronize the cart contents when the checkout starts, in that situation you'd need to include the following code (assuming the same cart's contents of the previous example):

pagetype: "checkout",
cart: [
   {
      id: 13,
      quantity: 1
   },
   {
      id: 27,
      quantity: 3	
   }
]
recommenders any This field is used when you want to show product recommendations in a given page type. As our solutions ables you to configure a lot of details, we have devoted a full section of this documentation to product recommendations. So if you want to understand how to fill this field according to your needs, please, read the next section.

Product recommendations are a powerful tool for eCommerce marketers, as they able to increase the overall conversion and average order value. In this section you'd learn how to configure BrainSINS to show product recommendations in your online store.

Recommenders Fields

The specification of the previous chapter does not include all the details regarding how to ask BrainSINS to show product recommendations. The field you need to include in our JSON format to show product recommendations is called recommenders, a list of recommenders configurations that allows you to show several product recommendations block in any given page of your online store. Each position of the list may contain the following fields.

Data field Required Description
recommenderId yes This is a numerical id of the recommender to be shown. You can choose the recommender behavior you desire in our management console, and then get the id of the recommender of your choice to include it in this field.
location yes Location refers to the id of the DIV you want to take as reference to include the recommendation block in your online store. We use that DIV as a reference to include the recommended products, so you can place them wherever you want.
position no This field is a modifier to the previous field (location). When you have chosen a current DIV's id in your online store as a reference to include the recommended products, you can specify to BrainSINS if you want the recommendations to be placed before or after that div, or if you want the DIV to be replaced with the recommendation block. The following image tries to show how the position field affects to where the user will see the recommendations in your online store:

How to place product recommendations

There are several positions according to wherever you want to place the recommendation block related to the chosen location:

  • replace: Replaces the location DIV contents with the recommendation HTML block.
  • before: Places the recommendation HTML block before the location DIV.
  • first: Places the recommendation HTML block as the first node inside the location DIV.
  • last: Places the recommendation HTML block as the last node inside the location DIV.
  • after: Places the recommendation HTML block after the location DIV.

Recommenders Examples

Let's check some examples to fully understand how the recommendations field works.

Example 1

An example of how to include product recommendations in a product page (the productId is 123). We want to load the recommender with id=2, and replace the contents on the DIV with id "recommendation-block" with the recommended products:



<script type="text/javascript">
var BrainSINSData = {
   pageType: "product",
   productId: 123,
   language: "es",
   recommenders: [
      {
         recommenderId: 2,    
         location: "recommendation-block",
         position: "replace"
      }
   ]   
};
</script>
]

Example 2

An example of how to include product recommendations in a category listing (the category is shirts). We want to load 2 recommendation blocks.

The first one is the recommender with id=13, and we want the recommendations to replace the DIV with id "recommendation-block-1". We want this recommender to show only shirts, so we have to filter the recommendations according to the category.

The second recommender is the recommender with id=29, and we want the recommended products to be located just before an existing DIV that have the id "product-details". We want this recommender to show any type of products, so we are not going to filter the recommendation results.



<!-- BrainSINS Code Starts -->
<script type="text/javascript">
var BrainSINSData = {
   pageType: "category",
   categories: "shirts",
   language: "es",
   recommenders: [
      {
         recommenderId: 13,    
         location: "recommendation-block-1",
         position: "replace",
         filter: "any"
      },
      {
         recommenderId: 29,    
         location: "recommendation-block-2",
         position: "before"
      }
   ] 
};
</script>
<!-- BrainSINS Code Ends -->
]