Initialize the Product Guide with URL Parameters

Note

This page describes how you can initialize your Product Guides by using URL parameters. This helps to deeply integrate the Product Guides into specific customer journeys or click paths and also allows you to build powerful landing pages that deep-link into specific Product Guide situations.

Goals of using URL parameters

You can use URL parameters for the following goals or use cases:

• preset answer options for e.g. banners or landing pages: You want to create a banner with e.g. “new full-suspension mountain bikes for women”.

  • you then do not want to start the “blank” Product Guide, but preset the “gender question” to female

  • Perhaps you also want to skip the stage of the Product Guide containing the “gender question”, so that the Product Guide directly opens with the next stage

• the same logic applies for landing pages that address a specific target group, or highlight your latest product innovations (e.g. “explore our new carbon fibre e-bike series.”). This example would preset answer options of material or product category, as well as perhaps a “new” flag or a product launch date attribute.

• preset the Product Guide with user profiles

  • maybe your CMS or shop system is smart enough to dynamically display banner content based on a user profile that you tracked, e.g. you know the user is female. This technically is the same banner example as explained above, except that the banner was displayed dynamically from your shop system

  • if your CMS or shop system has the capability to manage user profiles via e.g. user login functionalities. You could then implement intelligent functions to utilize the full power of the Product Guides, e.g.

    • store the purchase history of the user and hand over favorite brands to the user

    • store the order return history

Examples

An integration URL as generated in the Workbench’s Publish View can be extended by various parameters to preset answer options or move to a stage initially. These parameters can be supplied in the query part or the hash part of the URL. Here is an example using query parameters:

//service.excentos.com/demo/DE/app_Bike-Advisor/en_US/loadadvisor?theme=default&$bike_type=mountain_bike&$gender=male

It also possible to use hash parameters:

//service.excentos.com/demo/DE/app_Bike-Advisor/en_US/loadadvisor?theme=default#$bike_type=mountain_bike&$gender=male

Or even mix both but this is not recommended. Note that the parameters are only evaluated the first time the advisor is loaded, the theme changes or the channel ID was modified. Any other changes have no effect. You can change this by adding the ‘xcReset’ parameter.

How to identify the IDs of questions and answer options

In order to set the URL parameters, you need to identify the IDs of the corresponding questions and answer options. The easiest way to identify the IDs is to look them up at the corresponding *questions* and *answer options* in the Concept Board of your Workbench account. Here is an example of the **question ID**:

Here is an example of how to look up the ID of an answer option:

Overview of possible parameters

Parameter	Description	Example
$question_id=option_id	Sets the question to the answer option. For multi-selectable questions the option is added.	$bike_type=mountain_bike
xcStartAt=stage_id	Sets the current stage to the given ID.	xcStartAt=xcAjaxClient.wizard.recommendations
xcReset	Clears any previous values in the user profile.	xcReset

Set initial answer options

You can select answer options by adding one or more parameters of the form

$question_id=option_id

//service.excentos.com/demo/DE/app_Bike-Advisor/en_US/loadadvisor?theme=default&$bike_type=mountain_bike

For single selectable questions, this removes any previous option value. In multiple-selectable questions the option value is added.

If you want to select more than one option of a question (only possible for multi-selectquestions), simply add another parameter with the same name:

$question_id=option_id_1&$question_id=option_id_2&...

//service.excentos.com/demo/DE/app_Bike-Advisor/en_US/loadadvisor?theme=default&$bike_type=mountain_bike&bike_type=race_bike

Note: The any value containing special characters for questions using automatic option mapping are automatically escaped.

Move to an initial stage

Starting the Product Guide in another stage than the first is done by the parameter:

xcStartAt=<internal path without 'groups'>

//service.excentos.com/demo/DE/app_Bike-Advisor/en_US/loadadvisor?theme=default&xcStartAt=xcAjaxClient.wizard.recommendations

Forcing a fresh user profile

Sometimes, the advisor is required to start with a fresh profile. The parameter ‘xcReset’ does just that. But it also clears the user profile anytime the page is refreshed or the user navigates back to the advisor.