1. Platform Implementation Docs
  2. Custom Platform Implementation Guide

Platform Implementation Docs

Custom Platform Implementation Guide

Introduction

This step-by-step guide covers everything you need to implement Shopbox on a custom platform.

Implementation and Staging

Generally it's best to get going with the Shopbox tracking script on production as soon as possible as this is the data we use to train the AI. We also prefer to do the training on the live data but can use staging data if needed but will be swapped out for the live data at some point as we don't keep track of both sets of data. This means that the shopbox product cards on the staging site will redirect to the live site. However, this is expected behaviour and does not cause issues for the functionality.

Shopbox stores basic information locally on devices. This information is cleared when the browser history is cleared. We do not track users across other sites, only on your domain.

You can add this to your cookie policy if needed:

“We use local storage to enhance your shopping experience by remembering products your device has viewed, allowing us to show better recommendations. This data is not linked to external information and is used solely within our store.”

Implementation breakdown

Step Requirements
Step 1 / Part 1 Setup page detection classes in page body tags.
Step 1 / Part 2 Insert the Shopbox tracking script into the site header.
Step 2 Generate Product and Order Feeds and begin delivering them daily.
Step 3 Check-in with your Shopbox Onboarding Manager.
Step 4 Use our API endpoints to build FE components for your store.
Step 5 Reaching out to our support/CS team.

Step 1: Add Shopbox Tracking Components

Part 1 - Page detection

Add a class name to the BODY TAG for each of the following page types:

Homepage Example:

<body class="sb-homepage">...</body>
Page Type Class Name
Homepage sb-homepage
Collections (PLP) sb-collection
Product Details sb-product-details
Search Results sb-search-results
Cart sb-cart
Order Confirmation sb-order-confirmation
*Checkout Success <div class="sb-order-id">123456</div>
NOTE

The Checkout Success is intended to be a hidden div element within the body of the page. The ID it contains should corrolate with the Order ID from the Magento API.

Part 2 - Tracking script

Insert our tracking script into the header of your site (both staging and production).

INFO

Your onboarding manager will have provided the required sbid (Shopbox ID).

Tracking Script Example:

<script>
    document.addEventListener('DOMContentLoaded', () => {
      var sbid = 'CUSTOMER_ID_GOES_HERE';
      var t = document.createElement("shopbox-app-v2"),
          s = document.createElement("script");
      t.setAttribute('cid', sbid);
      s.type = "text/javascript";
      s.async = true;
      s.src = "https://widget.shopbox.ai/js/app.js";
      document.body.appendChild(t);
      document.head.appendChild(s);
    });
</script>

Testing Part 2:

If you inspect any page on your domain and check under the Network Tab you should be able to see the scripts indicated in the below screenshot. Please let us know if you have any failure status codes as there could be a reason our server is unable to contact your own domain.

Magento screenshot

Step 2: Set Up Product and Order feeds

You will need to generate both product and orders feeds that are delivered daily via SFTP to Shopbox. Both feeds should be in a JSON format and the structure required is contained in the links below.

Once you have generated the feeds, upload them to the sFTP and inform your Shopbox contact. They will check the feeds and ensure they meet the specs required. Once cleared these can start to be sent daily (we suggest just after midnight regardless of your time zone).

NOTE

The instructions of how to upload to the sFTP location should have been already setup and sent to you. If not please reach out to your Shopbox contact.

Step 3: Align with your Shopbox onboarding manager

At this point, please be sure to align with your onboarding manager that steps 1 and 2 have been completed successfully. If everything is in order we will be able to build the AI model which should mature in over the period of a week before you continue to Step 4.

Step 4: Building Shopbox Components

WARNING

Your onboarding manager will let you know once the modelling has been completed on our end. - It typically takes a week after steps 1 and 2 have been completed. Until then, our endpoints will return blank results.

Also, note that you will require an API Token to use our API endpoints. Please reach out to your onboarding manager if you are not able to generate your API key from our hub.

Part 1 - PDP Components

For the PDP we generally use the following endpoints. We generally recommend that the grids are added higher up on the page instead of too far down.

Here is an example of what could be expected:

Magento screenshot

Here is an example of how to build a Find Similar component powered by our API.

TIP

Please be sure to use the full product URLs from the Shopbox API response. The urls we return from the API contain additional parameters we use to track clicks on products we have recommended through the API. Please DO NOT STRIP THESE PARAMETERS. If so we will not be able to provide any information on attributes sales through the API.

Additionally if you use an add to cart option on your product cards, we ask you to review our analytics doc so we can keep track of products via the quick add.

Part 2 - Homepage Components

For the Homepage we generally use the following endpoints. We generally recommend that this should appear right below the hero banner at the top of the homepage.

Here is an example of what could be expected:

Magento screenshot

Step 5: Requesting Support (Post implementation)

If you ever require any assistance with Shopbox please be sure to log a support ticket here.

Previous <- API Component Analytics
Next Magento 2 Implementation Guide ->