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

Quick Test

jumpstart with integrating a Product Guide example right away

2

Detailed Explanation

everything you need to know about site integration and how to optimize it

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 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?
Please note that in our contract, we assume that you successfully passed the Quick Test and that we have stable and functioning stage and service environments throughout the initial implementation and ongoing Service Operation.

troubleshooting

If you encounter any problems, please refer to our troubleshooting guidelines.

Detailed Documentation

Read on here if you would like to fully understand the integration options provided by us.

The integration code
consists of two components:

JavaScript Logo
JavaScript Loader Code
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.
Html Logo
HTML Positioning
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

excentos will provide you a separate document for your project-specific documentation
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

Please insert this JavaScript code either in <HEAD> or <BODY>. If inserted in the <HEAD> (which is preferable), make sure it is inserted after the site's default scripting (esp. jquery.js). If you cannot place code in the html-<head> you may place the <head> code in the <body>, too. Integrating the script part at the end of the <head> instead of in the <body> leads to faster startup times of the Guides.

HTML Code

The HTML Code defines
where the excentos JavaScript code
will inject the application within your page

There is required HTML code (needed in any case), recommended code and optional code.

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:

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 |  
  
 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

We require several Integration Pages to cover Stage and Service Environments for effective testing of changes within the Product Guide and / or your Shop/Website. Please read the documentation on Service and Stage Environments that also defines which Integration Pages for which Environments you need to provide.

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=https to 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.