Centra installation guide
Hello Retail can be integrated with the Centra ecommerce platform in a few different ways.
The basic question is whether you want full control and ability by utilising our API, or want more of a “fully managed” solution.
Seeing how Centra is an advanced platform targeted at more advanced shop owners, we generally recommend to take as much control as possible and utilise our API.
If in doubt you can always talk to your Hello Retail contact about the best approach for you.
Regardless of how we are integrated, the following two headlines sums up the basic steps that needs to be completed:
Synchronisation of orders, products, categories and content:
In order for Hello Retail to serve relevant content, we need to know about your shop. The synchronisation uses the Centra Checkout API for products, categories and content, and Centra Order API for orders.
Hello Retail will need API credentials with the necessary read permissions and some additional info to set it up:
Centra Checkout API
- API token with read permission for products, pricelists and categories.
- URL/endpoint where the checkout api for your store is available.
Centra Order API
- API token with read permission to orders and products.
- URL/endpoint where the order api for your store is available.
General:
- Language ISO for your store.
- Market id for your store.
To set up an API in Centra, login to your centra admin and go to "Store settings", here you can add plugins to your store from a list of viable plugins. Order API and Checkout API are in this list. After you have added the API plugins to your store, you can then open their settings and configure the API key, permissions and restrictions.
As for the API key, we suggest you use a random key generator of some sort.
If in doubt on how to provide this you can ask Centra support.
Insertion of the helloretail.js script:
To establish a connection between your shop and our system, the essential component is the helloretail.js script. The script needs to be present on all pages of your webshop, except maybe the order submit page. it needs to be present on the order confirmation page though.
You can integrate the script by either manually inserting it at the bottom of the header or utilizing something like Google Tag Manager:
<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script>
window.hrq = window.hrq || [];
hrq.push(['init', {}]);
</script>
Different implementations of Hello Retail solutions on your shop:
When implementing our solutions to your Centra shop you need to decide on one of the following approaches. You will be deciding between "ease of installation" and "ability and control".
General info about Recommendations: https://developer.helloretail.com/sdk/recoms/
General info about Search: https://developer.helloretail.com/sdk/search/
General info about Pages: https://developer.helloretail.com/sdk/pages/
- API JSON: With this approach you would use our API to fetch a basic list of products for a given recommendation box or search query. The result would be served to you as a list of JSON Objects representing the products. You would then use this list of products in combination with your own logic and templates to create the final elements that you insert into your DOM.
One of the greatest reasons for using this approach is that it allows you to combine the response from our API with session/user specific data from the Checkout API - think translations, vat rates based on geolocation, special price lists etc.
This would also be the way to go for a backend integration ensuring smooth delivery of the frontend to the end users.
Read these guides on using our API with this approach:
https://developer.helloretail.com/api/recoms/
https://developer.helloretail.com/api/search/
https://developer.helloretail.com/api/pages/
If you want to use this approach but dont want to use the REST api to integrate it in your backend, you can also use the SDK through the frontend: https://developer.helloretail.com/sdk/recoms/javascript_sdk/
https://developer.helloretail.com/sdk/search/javascript_sdk/
https://developer.helloretail.com/sdk/pages/javascript_sdk/
- API template: With this approach you would use our API to fetch pre-generated templates ready for insertion into your DOM. This option relinquishes some control and may prove difficult in handling session/user specific data as mentioned in the API JSON section above. Another thing to note is that the template will be configured in hello retail, so there is inevitably going to be more work when you want to update your design. Read these guides on using our API with this approach:
https://developer.helloretail.com/sdk/recoms/javascript_sdk/
https://developer.helloretail.com/sdk/search/javascript_sdk/
https://developer.helloretail.com/sdk/pages/javascript_sdk/
- Auto-insert and placeholders: With this approach you would not use our API, but instead simply Insert div elements in your DOM to indicate where Hello Retail's elements should be injected. This method requires minimal technical knowledge and effort, as the helloretail.js script handles the API call and result injection for you. However this method has the same drawbacks as mentioned by the API Template approach above.
You can read more about this approach here:
https://support.helloretail.com/t/q5aq0y/how-to-add-product-recommendations-to-
Specifically for the Hello retail pages feature, you need to look at this guide:
https://developer.helloretail.com/sdk/pages/spa_example/
Generally we recommend to go with the API JSON approach to ensure the best possibilities and to retain as much control as possible of your site.
Tracking of important events:
We need to know about orders being placed, what is in a session cart, what pages are being viewed and what elements are being clicked. These events are the foundation of our system understanding your shop and essential in serving the best possible content through our features.
Hello Retail offers both server-side and frontend tracking options. If you go with the JSON API solution proposed in the section above, we would recommend that you implement server side tracking, however if you are going with the fully managed "Auto insert" approach then the frontend tracking would likely be the way to go for you:
- Server-side tracking: Follow the instructions in our server-side tracking guide for detailed implementation steps and a more thorough description of the approach:
https://developer.helloretail.com/guides/tracking/server_side_tracking/
- Frontend tracking: Follow the instructions in our general tracking guide for detailed implementation steps and a more thorough description of the approach: https://support.helloretail.com/t/83htvh3
For view tracking and click tracking you can let the script handle that automatically although we recommend that you do it manually - for more info on this read the comment below regarding SPA's.
Guide on manually doing view tracking:
https://developer.helloretail.com/sdk/tracking/view_tracking/
Guide on manually doing click tracking:
https://developer.helloretail.com/sdk/tracking/click_tracking/
It is worth noting that since you are working with a Single Page Application (SPA's) you might need to call the .reload() function of the helloretail.js script whenever essential content is changes. This would be the case if you rely on the helloretail.js script to automatically do view and click tracking. It is recommended that you handle these events manually to avoid calling .reload() as it involves some overhead loading.
You can read a bit more about page tracking and SPA's here:
https://developer.helloretail.com/guides/spa/page_tracking_for_spa/
Please note that Hello Retail's search functionality does not include built-in translation engines or currency conversion tools. Consequently, if a customer searches for a product using a different language or filters search results based on a currency different from what is indexed, they may not obtain the desired results. To overcome this limitation, you can build your search functionality by using the API to find products and handling the frontend/UI yourself.