How To Integrate the
Product Guides into your Website
This documentation describes how to integrate the excentos Product Guides into your Shop / Websites
and which parameters can be used to set the Product Guide application, country / market and locale.
Please read the how-it-works#integration section first for a general introduction,
some examples and general FAQ.
This documentation consists of 2 parts
1. Create an empty integration page within your Shop/WebsiteJust simply add an empty page within your Shop System or CMS.
Typically, this integration page should contain your Website's header and footer (but this is not required).
2. copy the test integration code into your pageUse exactly this test integration code snippet and copy it into the empty integraton page you've just created.
Insert the code at the position where you want the Product Guide to be displayed.
Please don't modify the URL:
1 | <!-- begin excentos test integration code --> 2 | <script src="//service.excentos.com/demo_marketing/DE/app_Camera-Guide/en_US/loadadvisor?theme=default"></script> 3 | <!-- end excentos test integration code // start content area where Product Guide is displayed --> 4 | <div id="xc_application"> 5 | <div id="xc_application_pane"></div> 6 | <div id="xc_loader"></div> 7 | </div> 8 | <!-- end excentos content area -->
3. save the integration page and check if it works!
Just save / commit your newly created integration page, and open it in your web browserNow, you shall see the Product Guide in your integration page. Use this Test Product Guide as a reference to check how it should look like.
Once your individual Product Guide is implemented, you only need to change the parameters in the integration code URL and you'll see your productive Product Guide instead of the test Product Guide.
test criteriaTo make sure the Product Guide and its entire functionality works, please make the following tests. Refer to the Test Product Guide and see below for troubleshooting:
- basic functionality: the advisor is loading for a short time (you should see the loading animation for not longer than 5 seconds) and after that displayed properly and you can interact with it, e.g. select answer options.
responsiveness: the Quick Test displays our default theme. It behaves responsive to any page width larger than 320px. Please test the responsiveness inside your website at least on a desktop and a mobile device.
(depending on your environment, please make sure you reload the page if you played with a browser window width to reset the client's width)
- explanation: are explanations shown if you select the little (i)-icon next to questions or answer options?
- recommendations: are ther recommendations in the last stage shown? Are there product images?
If you encounter any problems, please refer to our troubleshooting guidelines.
The integration code
consists of two components:
The HTML positioning defines at what position in your
1 | <!-- begin excentos site integration code --> 2 | <script 3 | src="//environment/projectName/systemName/applicationName/locale/loadadvisor?theme=themeName"> 4 | </script> 5 | <!-- end excentos site integration code -->
Parameters used by the Integration Page
(CHECK YOUR PROJECT-SPECIFIC DOCUMENT!)
describes the host name of the excentos webservice.
service is used for "live productive systems", and stage is used to test changes before being deployed live.
You shall provide separate integration pages per environment; please see our documentation on the environments and how to use them to effectively test, integrate and operate the Product Guides.
|projectName||e.g. Bikeshop, Jewellerybrand||your project name that can be used across several systems and applications.
Most of the times, we simply use your brand name.
|systemName||e.g. DE, UK, FR, B2B_FR||
the system defines a specific range of products and a specific configuration,
most of the times for one market or country.
We typically use the country's ISO country in uppercase letters.
Options that can be changed from one system to the others are e.g. product assortment, prices, recommendation behaviour, question flow, list of questions and answers displayed, content and images, general behaviour. A system can also be used to model B2B versus B2C applications based on the same core.
|applicationName||e.g. app_bikeadvisor, app_runningshoes||
name of the Product Guide application.
|locale||de_DE, en_UK, de_CH, de_AT, fr_CH||
the locale defines the language content displayed in the Product Guide.
We typically use the ISO code (but can deviate from it if required).
The locale can also be used to model different content for different target groups, e.g. a binocular Product Guide can use hunting-language and images for hunting fans and birding-language / images for bird observation gurus (and yes, these two target groups need to receive different buying arguments).
|themeName||e.g. mobile, desktop, default, desktop-longpager, desktop-wizard||
the theme defines the HTML/CSS style used by the Product Guide.
Every application can use several themes (e.g. Bike Advisor longpager, Bike Advisor Wizard. One theme can be used across different applications (e.g. Bike Advisor and Jewellery Advisor use the same Wizard). A theme can also be used to distinguish between several brands or to differently style the user interface for channel partners.
The HTML Code defines
will inject the application within your page
Required HTML Code
This code is required to display the Product Guide:
1 | <!-- begin excentos content area --> 2 | <div id="xc_application"> 3 | <div id="xc_application_pane"></div> 4 | <div id="xc_loader"></div> 5 | </div> 6 | <!-- end excentos content area -->
Recommended HTML Code
We highly recommend you adding this code to enhance the error handling:
Example including all the required and recommended HTML code:
1 | <!-- begin excentos content area --> 2 | <div id="xc_application"> 3 | <div id="xc_application_pane"></div> 4 | <div id="xc_loader"></div> 5 | 6 | <!-- fallback message (RECOMMENDED) displayed if the excentos server cannot display its own error message.
excentos supports several Environments
for effective development, testing and deployment procedures
In rare cases, we may encounter problems integrating the Product Guides into your shop or website.
Please read on for a first troubleshooting, or contact the excentos support.
If you encounter problems integrating the Product Guides, here are some potential reasons:
- visibility: in case the Product Guide is not entirely or not at all visible, please check if there are any <div> container or CSS collisions that might hide / overlay with the Product Guide.
namespace collisions: the CSS code used by your website may use the same namespaces as used by excentos.
excentos typically avoids this problem by own name prefixes, but hey, it may collide.
- not at all responsive: if the Product Guide does not at all behave responsively, please check if your integration page is entirely responsive. The excentos Product Guide can only be responsive if the integration page is responsive. Make sure your page uses a viewport meta tag, e.g. <meta name="viewport" content="width=device-width">
- problems with page margins / spacing: if there are e.g. more pixels on the left / right side around the Product Guide, or if it is not vertically aligned with your top menu, please make sure that there are no page margins / CSS rules set around the integration code of the Product Guide
- security problems (e.g. Product Guide doesn't load at all): cross-domain policies, blocked IP adresses, or collision of HTTP versus HTTPS may result in your website blocking any webservices delivered by excentos. Please make sure our servers *.excentos.com are whitelisted as a source for image- and script-tags on your website
product image not visible: (similar to security problems above): if the product image is not displayed, a possible reason is that your website / e-commerce system / IT configuration blocks cross-site content.
excentos uses an image server that is especially optimized to quickly deliver high-resolution images. It might be necessary to whitelist its IP adress in your environment.
FAQ and Further Information
How many Integration Pages are needed?
You need only one Integration Page per Product Guide for all of a Product Guide's functionality since it is a Single Page App.
However, we require an Integration Page in your stage system as well to early on test the Product Guide.
See the documentation of Stage and Service Environments to check how many Integration Pages in what Environment are required.
Can I create several Integration Pages for better linking into the Product Guide
Technically, you may have several Integration Pages for one single Product Guide, e.g. if you want to show the Product Guide within different page contexts with different intro texts / images. However, you don't need more than one Integration Page (see also FAQ above).
Another way to have multiple various entry points into your Product Guide is to have several Landing Pages. See our Marketing and SEO Concept documentation to learn how to create great Landing Pages and Content that guide many users into your Product Guides.
How does the Internationalization and different Product Assortments work?
If you require a different Product Guide behaviour for e.g. several countries / markets / product assortments / language variants, excentos will set up different systems to reflect those changes in the behavior.
The system only includes the products contained in your system-specific data exports (i.e. country / market feed) and will also only show the locale that you specified. The Product Guide integration code needs to include the system name and the locale.
Security / What Protocols are Supported / HTTP versus HTTPS
All excentos SaaS services are accessible via secure SSL connections ( https:// protocol). If your Integration Page is served via HTTP, add the parameter
xcScheme=httpsto your integration code, so it looks like this:
Content Security Policies
If you explicitly set a content-security-policy via HTTP header or HTML <meta> tag, please include the „service.excentos.com“ domain in the list of allowed domains for external scripts, images, fonts and stylesheets.