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
Quick test
This quick test allows you to jumpstart and test the integration before getting into the
details on how to optimize and configure
the site integration.
Just complete the following 3 steps and you'll see how easy it is to integrate the Product Guide
into your Shop/Website - or detect if there are any JavaScript conflicts between your systems and excentos.
1. Create an empty integration page within your Shop/Website
Just 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 page
Use 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 defer 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 browser
Now, 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 criteria
To 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?
troubleshooting
If you encounter any problems, please refer to our troubleshooting guidelines.
Detailed documentation
The integration code
consists of two components:
The JavaScript code loads the excentos webservice and its business logic.
The JavaScript code uses parameters that need to be set in your integration page.
The HTML positioning defines at what position in your
webpage the excentos JavaScript code will inject the application.
JavaScript code
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 -->
Example: //service.excentos.com/bikeshop/DE/bikeadvisor/de_DE/loadadvisor?theme=responsive
Parameters used by the integration page
of the parameter values used for your Product Guides. This general documentation only describes the meaning of the parameters and shows some general examples.
PARAMETER |
EXAMPLES(CHECK YOUR PROJECT-SPECIFIC DOCUMENT!) | COMMENT |
|---|---|---|
| environment | service.excentos.com / stage.excentos.com / test.excentos.com |
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. We always use lowercase letters. Including an "app" in the name allows more flexibility in the integration / JavaScript loader since we know that this depicts the 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. |
Where to insert the JavaScript code
HTML code
The HTML code defines
where the excentos JavaScript code
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 -->
In most cases, you may place this HTML code at the same position as the JavaScript-Code - this is actually what we've done in the Quick Test example above. There are rare cases of Shops/Websites that require the JavaScript-Code at another position than the HTML-code (e.g. in the page footer, in a separate JavaScript-block) and that's the only reason why we've separated HTML and JavaScript-code.
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.-->
Error handling
If the visitor has an incompatible browser, no JavaScript or if the excentos server is not available or in an error state, excentos automatically displays an errormessage to the user. If you want to prevent the case that excentos cannot even display the automatic error message, you can include the <div id="xc_fallback">. Please note that this happens in very rare cases only, especially if the user has JavaScript disabled or if the excentos server does not answer at all or not answer correctly. If you add the xc_fallback, please make sure you don't use relevant SEO keywords (e.g. avoid the name of your Product Guide and your product categories) – otherwise search engines might display the fallback 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.
Please use generic terms and AVOID good SEO keywords because otherwise the error message might be displayed by search engines --> 7 | <div id="xc_fallback"> 8 | <h2>Thanks for your interest in our search tools< /h2> 9 | <p>If you cannot start it please visit our <a href="/www.your-bikeshop.com/faceted-search">product search</a> or check whether your webbrowser has Javascript enabled.</p> 10 | </div> 11 | </div> 12 | <!-- end excentos content area -->
Required Environments
excentos supports several Environments
for effective development, testing and deployment procedures
User inputs
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.
Troubleshooting
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.
- JavaScript collisions: excentos uses a JavaScript / HTML5 client with all advantages of a Single Page Application. Most shops and websites also use JavaScript frameworks. In rare cases, the JavaScript framework of your system may interfer with the JavaScript framework used by excentos.
- 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:
src="//environment/projectName/systemName/applicationName/locale/loadadvisor?theme=themeName&xcScheme=https" -
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.
