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:
<!-- begin excentos test integration code --> <script src="//service.excentos.com/demo_marketing/DE/app_Camera-Guide/en_US/loadadvisor?theme=default"></script> <!-- end excentos test integration code // start content area where Product Guide is displayed --> <div id="xc_application"> <div id="xc_application_pane"></div> <div id="xc_loader"></div> </div> <!-- 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
|EXAMPLES(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:!--currently we don't have the possibility to add a welcome screen to the advisor. add this back in as soon as we have it.
Welcome Message (Optional)It is optionally possible to add a custom welcome screen that shows up before the Product Guide is shown. Do this by inserting the desired content into
<div id ="xc_xc_welcome"><div>. The Product Guide will only be shown after the user clicked on the interaction element with the tag <a id ="xc_showadvisor">. If required, excentos can configure a timeout that automatically switches from the welcome screen to the Product Guide content.-->
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 | !-- see commnt on welcome message above 6 | <!-- The welcome message is OPTIONAL. If you use it, find good keywords since this text is relevant for SEO. Replace our examples in the following text --> 7 | <div id="xc_welcome"> 8 | <h2>Use the Bikeshop Bike Advisor to find top recommendations and get great deals!</h2> 9 | <p>The Bike Advisor will guide you to find perfect bikes that fit your personal needs. 10 | <a id="xc_showadvisor">Start Product Guide</a> 11 | </p> 12 | </div> 13 |--> 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
During one browser session users can always return to the
Product Guide with all entries still active
If a user exits the Product Guide to the shopping cart or to product detail pages and returns afterwards all his inputs and entries remain active. excentos saves the user profil and always will show the last rendered view to the returning user. The user make use of his entered data as long as he is in the same browser session.
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
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.