Skip to content

Integration

Web components

The first step in enabling the web components is to add the script tags below to the web page. It's recommended to place them inside the <head> tag.

<head>
  <script src="https://cdn.esales.apptus.com/integration/v1/esales-fashion-polyfills.es5.js"></script>
  <script src="https://cdn.esales.apptus.com/integration/v1/esales-fashion.es5.js"></script>
</head>

Before the components can be used, they require an initialization configuration. This is done via the esales.init function, which will link the components to a specific eSales cluster and market.

This API will be available after the above script tags are executed.

<script>
  esales.init({
    webApiId: '<esales-web-API-cluster-ID>',
    market: 'UK',
    touchPoint: 'DESKTOP',
    productPageUrlPrefix: 'https://example.com/product/',
    searchPageUrlPrefix: 'https://example.com/search'
  });
</script>

After the above script has executed, the components should now be bootstrapped and ready to be used. The first step could be to add the <esales-search-assistant>. It is recommended to add it to the header and to make it available to all pages.

<body>
  <nav>
    <header>
      <esales-search-assistant placeholder="Search"></esales-search-assistant>
    </header>
  </nav>
</body>

Next, <esales-search-results> could be added to the search page. This page should match the URL provided by searchPageUrlPrefix mentioned above.

<body>
  <main>
    <esales-search-results></esales-search-results>
  </main>
</body>

With these steps done, it should now be possible to search via the eSales search assistant, showing the results on the search page via the search results component.

Live sample integration

A sample integration using both components can be viewed and tested using this JSFiddle set-up. Make sure to replace the webApiId with the one you have received from Apptus and press Run.

Order notifications

The sessionKey and customerKey can be retrieved from the component library API:

const sessionKey = esales.session.sessionKey;
const customerKey = esales.session.customerKey;

These keys can then be sent to the back-end that handles order notifications to eSales whenever a customer completes an order.

curl -i -X POST \
-d '{ "sessionKey": "5e856fae-235e-e02f-1e85-d19f67ccce5f", "customerKey": "5e856fae-235e-e02f-1e85-d19f67ccce5f", "market": "UK", "lines": [{"productKey":"P_555452-0446_UK", "quantity": 1, "sellingPrice": 10.35,  "cost": 5.1, "variantKey": "V1" }]}' \
-H "Content-Type: application/json" \
-H "Api-Key: YOURAPIKEY" \
"https://{CLUSTER-ID}.api.esales.apptus.cloud/api/v1/notifications/payment"

Continuous product feed

After gaining access to the cloud environment a retailer can use their cluster credentials to import data into Apptus eSales.

Before going live a data feed from the retailers systems to Apptus eSales must be set up. This is typically achieved by creating a program that queries a retailers database for changes and send updates to eSales accordingly. If the database is reasonably small (i.e. less than 100.000 items), full updates can be sent regularly.

For large databases only the modified items should be sent, this as a partial update. Some sites with frequent updates to for example price and stock_number can use attribute modification. This is also helpful if the stock_number data is stored in a separate system.

The data files is sent to eSales using the standard HTTP POST protocol. If the data is not valid eSales will return an error message with descriptions of the errors in the file. Apptus eSales will reject incoming updates while an update is being processed, so the data feed software must be set up to run updates one at a time.

Error handling

All updates in eSales are atomic (i.e. either the full update or nothing will be run), to make it easier to recover from errors. An error can be caused either by import data being invalid or because of other factors, such as network errors. If an error is received, the update can be safely rerun once the connection is restored or import data is fixed.

Apptus eSales produces the following error types.

Code Description
403 Incorrect cluster credentials.
404 Cluster not found.
4xx The import contained errors. The response body contains more information about the error to help with corrections to the data feed generation.
5xx Server error such as cluster unavailable or busy. If 5xx errors are received, contact support@apptus.com and attach any information found in the response body.

If a retailer experiences persistent network errors they should first contact their network administrator. If the problem seems to be on Apptus end, contact support@apptus.com.

Temporary network errors

The data feed software should handle temporary network errors without manual intervention as this is usually done through retries.

Optional integration steps

Data priming

Apptus eSales uses sales statistics to improve the quality of the results. Data priming can be used to initialize Apptus eSales with historical sales statistics from other systems.

Data priming is made by Apptus based on an XML-file that the retailer supplies to Apptus. A retailer can contact support@apptus.com for more information about data priming.

×