Working with panels¶
Panels and zones are the building blocks of a site using Voyado Elevate 3. A zone contains panels and most often represent an entire page, or a specific part of a page. Management and configuration of panels and zones are done via the Voyado Elevate manager.
Selecting panels¶
Voyado Elevate has 36 predefined panels grouped into their areas of usage. These groups are Ads panels, Customer panels, Navigation panels, Product panels, Recommendation panels, and Search panels. Most of the predefined panels support personalisation. What panels to use is entirely based on what the purpose of the zone is.
Panel hierarchy¶
Panels and zones are ordered in a hierarchy. The actual hierarchical position of panels within a zone does not affect the panel path when published, but it is recommended that it follows the order it will be used on a site. When the panel hierarchy is published, each public panel have a path that is based on the panel and zone name and can be queried via the Web API.
General settings¶
Each panel and zone have general settings that includes a name, a description, and more. The names must be unique and is recommended to be descriptive of the use of the panel or zone. The panel hierarchy cannot be published if two or more panels or zones have the same name.
A panel or zone should not be renamed after its initial publishing. All statistics for panels and zones are connected to their published path. As the path is based on the panel and zone name, statistics will be reset when the identifying path is changed.
| Panel property | Description |
|---|---|
Name | The name of the panel. The panel path is used for statistics and is based on the panel name. The panel name must not be changed once its parent zone is published. Required property. |
Description | A description of the usage of the panel on the site. |
Visibility | The visibility state of the panel when the panel hierarchy is published. Can be either Non-public or Public. A panel must be set to public to be directly queried via the Web API. This setting is only available when a panel is not in a zone. |
Duplicates | The setting for how the panel should handle duplicate products. Can be either Keep, Allow Removal, or Force Removal. For more information see Deduplication. |
Local attributes | Custom attributes as key-value pairs such as CSS classes or ids that will be presented when executing the panel. |
| Zone property | Description |
|---|---|
Name | The name of the zone. The zone path is used for statistics and is based on the zone name. The zone name must not be changed once its is published. Required property. |
Description | A description of the usage of the zone on the site. |
Visibility | The visibility state of the zone when the panel hierarchy is published. Can be either Non-public or Public. A zone must be set to public to be directly queried via the Web API. |
Subpanels | What order the panels within the zone will be handled. Can be either As in hierarchy, Optimize order, or Split test. |
As in hierarchy | Setting of Subpanels. The order of panels is the same as in the panel hierarchy. |
Optimize order | Setting of Subpanels. Optimise panel order through additional settings. Can be either Viewed product, Current customer, or Searched phrase. |
Split test | Setting of Subpanels. Selects one panel out of the sub-panels uniformly at random, see Panel split test. |
Viewed product | Setting of Optimize order. Optimise the panel order according to how well each sub-panel has performed historically when a specific product was being viewed. Requires a supplied product_key or variable_key argument in the panel query. |
Current customer | Setting of Optimize order. Optimise the panel order according to how well each sub-panel has performed historically for the current customer. Requires the customerKey argument with the id for the current visitor in the panel query. |
Searched phrase | Setting of Optimize order. Optimise the panel order according to how well each sub-panel has performed historically when the result of a specific search query was shown. Requires a supplied search_phrase argument in the panel query. |
Maximum number of subpanels | The number of panels to display. 0 < Maximum number of subpanels < 10 000. Required when using sub-panel orders As in hierarchy and Optimizer order. |
Local attributes | Custom attributes as key-value pairs such as CSS classes or ids that will be presented when executing the zone. |
Panel arguments¶
Result panels can accept arguments in addition to any default or required values. Argument values can be defined in a parent zone, in the result panel itself, or left undefined. Arguments that are left undefined at the root of a panel hierarchy must be supplied with a panel query at the time of the request.
Any arguments supplied in a panel query that are already configured for the panels will be ignored. The format of required parameters supplied in a panel query differ between Web API v2 and Web API v1.
Configure arguments¶
Every predefined panel have arguments that can be either configured before publishing or supplied via a panel query. Arguments that are configured for a panel or a zone supersede any argument supplied in a panel query.
Arguments not configured for sub-panels in a zone will be available to configure at the parent zone level. If more than one sub-panel in a zone take the same argument, a sub-panel can have that argument configured while it is configured for the zone as well. The argument in the sub-panel will then override the argument from the zone for that specific sub-panel.
There are no specific configurations that are recommended to always, or never, use. Configuring arguments for panels have both their benefits and drawbacks. The main benefit is that there are less need for changes in the code that performs the panel queries and such code release dependencies.
The drawbacks include a risk of increased complexity and potential errors. If most arguments are configured, there will be a huge amount of zones with the same basic set-up but with different arguments that could be supplied in a panel query. For sites with multi-language markets it may be easier to send in attributes in a panel query rather than having near identical panel configurations for each language.
Test arguments¶
It is recommended to test the panel and zone configuration and their arguments before publishing the panel hierarchy to a cluster. This helps to ensure that the panel hierarchy handles incoming and configured arguments correctly. A test will not run unless the arguments for the panels and zones have valid parameter values.
The additional arguments Market, Customer key, and Session Key can be added to a test, and may be needed depending on panel use. A test is performed against an active cluster and the result can be returned either as a JSON-style hierarchy or as XML. The arguments used during the test will not be saved to the panels and zones.
Creating zones¶
Zones are created within the Elevate Manager and predefined panels are added into them by drag and drop. A zone will omit any sub-panel that is empty in a result, and panels within a zone will process arguments simultaneously and independently of each other. A zone can contain multiple zones.
optimized sub-panel strategy¶
The Optimize order sub-panel setting of a zone enables Elevate to dynamically order the panels based on click-through rate. An additional setting of either Viewed product, Current customer, or Searched phrase must be configured to determine which context the click through rate is calculated. Each setting require different arguments either as a query to the zone or as a configured argument.
The optimized sub-panel strategy is intended as a manual evaluation of strategies during a limited time.
Maximum number of sub-panels¶
A maximum number of sub-panels must be set when using the sub-panel orders As in hierarchy and Optimizer order. The value can be between 0 and 10 000. This setting can be used to control the results based on what sub-panel order is used, as a zone will omit any sub-panels that are empty in a result.
When using the sub-panel order As in hierarchy, the setting can be used to achieve backfill when all other sub-panels within the zone return empty results. When using the sub-panel order Optimize order, the setting can be used to let sub-panels compete against each other and only present the panels that perform the best.
Panel split test¶
The panel split test setting can be used when there is a need to manually measure how and why one type of sub-panel outperforms another. Normally the Optimize order setting should be used for automatic panel testing.
The setting selects one panel out of the sub-panels uniformly at random. There is no backfill between the sub-panels if the chosen sub-panel is empty. If backfill is required, the backfill must be within the sub-panels. To have backfill of an entire panel, see Advanced. There is no setting for a maximum number of sub-panels. This is to preserve fairness in the ongoing test.
The panel split test strategy is intended as a manual evaluation of panels during a limited time. Before configuring a panel split test, it is recommended to contact Voyado Support.
Reusing panels¶
Some panels and zones can be reused on several pages, such as a top navigation or a Search as-you-type style zone. Reusing panels for several pages, such as a category navigation on brand pages and category landing pages, allows Elevate to split statistics of the panels between the pages.
Publishing panels¶
Panels will be published to a selected cluster. Publishing the panels will overwrite the current panels on the selected cluster. Only panels and zones that have Visibility set to Public can be queried.
Querying panels¶
Panel queries are the main way of fetching results, such as products or ads from Elevate. Panels and zones can be queried through the RESTFul API or via the JavaScript library when the panel hierarchy for a site has been published. A successful query returns the panel content in flattened and serialised JSON format.
Parameters that have not been set in a panel configuration or have a default value in predefined panels has to be sent as arguments. Panels in a zone will process arguments simultaneously and independently of each other.
An error message will be returned if required arguments are not configured or supplied in a query.
Querying for multiple results¶
A single query can be used to populate an entire page with different data, for example fetching a product listing with category information and faceting options related to the listing at the same time. This can return unexpected results, or break the panel query, if the panels use the same parameter names in the arguments, but does not accept the same values.
This can be resolved by changing the parameter names for panels involved in the query using the Elevate Manager. The following parameter names in arguments are recommended to rename if used when querying for multiple results: sort_by, presentation_attributes, window_first, window_last, and filter.
In the example above, to keep sorting of both the product listing and the category listing dynamic, at least one of the sort_by arguments must have the parameter renamed. As the product listing is determined to be the primary panel in the query, the category panel will have its sort_by argument renamed. The structure is similar to when using filter variables as placeholders for values in filter expressions. In the Elevate Manager, the setting for sort_by will be changed to sort_by = ${cat_sort_by=relevance}. This enables both a new name, cat_sort_by, and the inclusion of an optional default value, relevance.
| Renaming instance | Suggested default value |
|---|---|
| Sorting arguments | relevance |
| Pagination arguments | window_first=1 |
| Filter arguments | UNIVERSE or EMPTY |
Escaping characters¶
Arguments to panels may need to have some characters escaped. Even though the attributes used for filters, facets, and search are configured with their own refinements that may include escaping of characters, it is recommended to sanitize input from visitors. Characters can be escaped with a preceding backslash, e.g. \' and \\.
The following characters must be escaped for filters:
'\
The following characters must be escaped for facets:
,:\|
Best practice¶
Following are several common page and zone types and examples on how they can be created and used with different panel and zone combinations.
Home page¶
A home page has several purposes, for both new and returning visitors, and is one of the page types that use a wide variety of panels. Combinations of campaign optimized ads, personalized recommendations, and lists with top selling products can be used to a create a dynamic and relevant experience for all visitors.
Example¶
The following example describes the panel hierarchy of a home page optimized for a wide target audience that also includes personalisation for returning visitors. The page consists of an Ad information panel where a selected number of campaign ads can be shown followed by two zones, one with the panels for the main column and one with the panels for the right column.
The first zone includes a Product list panel with personalized products filtered by a campaign with the filter argument, an Ad information panel with personalized live products, an Ad information panel filtered by a campaign with the filter argument, a Recommend based on customer panel, and another Ad information panel filtered by a another campaign with the filter argument.
The second zone includes two Top sellers panels where the first panel show site wide top sellers. The second panel show top sellers within a certain category by using the selected_category argument.
Top navigation¶
The top navigation is commonly present on all pages on a site. The main purpose is to assist visitors in finding what they are looking for. But it can also be a space were relevant campaigns for the different navigation categories are presented without disturbing the browsing experience.
Example¶
The following example describes the panel hierarchy of a zone containing the panels for a top navigation with an additional ad information panel to optimise screen real estate and show relevant campaigns for each category.
The first panel is a Category overview panel using the root_category and depth arguments to retrieve a list of first level of sub categories of a specified root category. The Category navigation panel returns the category navigation tree with the selected_category category argument. The Ad information panel returns an ad suitable for the root category.
Product listing page¶
Visitors that are browsing a site usually end up on a product listing page where products of a narrowed down category or department are shown. A product listing page can take several forms depending on how panels and personalisation are used.
Facets are commonly used on product listing pages to narrow down a product set based on product attributes. These can be either a preconfigured set or a dynamic set based on the products available.
Example 1¶
The following example describes a product listing page with few panels focusing on effective product filtering and relevant personalisation. The zone is includes four panels and the selected_category argument is used by all panels.
The first panel is a Category breadcrumb panel listing the parent categories from the selected_category argument. The second panel is a Category overview panel that return category tree data including a product count.
The third panel is a Facets panel using the product attributes from the products present in the fourth panel, the Product list panel. The Product list panel is sorted by relevance to present the best products from the data set and to enable personalisation and adjust to trends live.
This type of product listing page is highly dynamic where the facets panel effectively narrow the product set within a category for the product list page to sort.
Example 2¶
The following example describe a product listing page where the available facets for product filtration are predetermined and a mix of top sellers and personalized product listing is used. The zone is includes five panels and the selected_category argument is used by all panels.
The first panel is a Category breadcrumb panel listing the parent categories from the selected_category argument. The second panel is a Category navigation panel that returns the child categories of the selected category. The third panel is the Facets panel filtering product attributes for this category.
Panel four is a Top sellers panel where the top selling products for the category is returned. The fifth panels is a Product list panel where personalized products within the current faceted dataset are returned. The settings for duplication can be changed to avoid duplicate products in the Top sellers panel and the Product list panel.
Product details page¶
The main goal of a product details page is to make a conversion. However, if a visitor has arrived to the page from an external search provider it is a good idea to provide similar products that may interest the visitor as well. Additional panels can be used for cross- or up-selling.
Example¶
The following example describe a product details page with additional panels for cross- and up-selling. The zone consist of four panels and the product_key argument is used by all panels.
The first panel is a Product breadcrumb panel listing the parent categories from the product_key argument. This enables a visitor arriving from an external search provider to easily view the category of the product. The second panel is the Product information panel that return all product information, including variants from a products argument that uses the product_key as its value.
The third panel is the Recommend based on product panel that can be used to up-sell similar products. It can take both the product_key or the variant_key from the Product information panel. The fourth panel is a Those who bought also bought panel that can be used to cross-sell accessories or other related products.
Search as-you-type¶
Search as-you-type is a feature that is known by more than one name, such as autocomplete search and quick search. The feature is usually built as a zone with several panels and is present on all pages on a site.
Example¶
The following example describe a search as-you-type zone containing four panels. The first panel is a Product suggestions panel using the search_prefix argument to find products. The second panel is a Search hit count panel that returns the number of products found.
The third panel is an Autocomplete panel that returns search phrase suggestions based on the search_prefix argument. The fourth panel is a Category suggestions panel that returns product categories that matches the search_prefix argument. Interactions with the Autocomplete panel and the Category suggestions panel should send the visitor to a Search result page.
Search result page¶
The search result page has one main purpose and that is to help visitors find what they are looking for. A search result page can personalise products and use facets to narrow down the search results.
Example¶
The following example describe a search result page that is a zone that includes a Facets panel and a Search zone. The Search zone contains three panels, a Search hit count panel, a Did-you-mean panel, and a Search hits panel.
The search_phrase argument should be sent in the panel query to the search result page zone to be used with all the panels. The Facets panel should only return configured facets for the products returned in the Search hits panel. The Search hit count panel will return the number of products found and the Did-you-mean panel will return a number of suggestions, commonly one phrase.
Depending on how the page is implemented by a retailer, the suggestion returned with the Did-you-mean panel can be used differently. If the product count is below a certain number of products, the suggested phrase can either be displayed or a new panel query to the zone can be performed using the suggestion as the search_phrase argument.
The Search hits panel will finally return the products found using the search_phrase argument.
Shopping cart page¶
The shopping cart page is commonly the last stop before a visitor proceeds with a checkout process. This allows for cross-selling to increase the average order value by boosting products that are either commonly bought together, or that will reward the visitor with perks such as free shipping.
Example¶
The following example is a shopping cart page that is a zone with three panels. The first panel is a Product information panel where the items in the visitors shopping cart are returned with the products argument.
The second panel is a Recommend based on cart where the cart argument is used to return products based on the products in the current shopping cart. The third panel is a Those who bought also bought panel that can be used to cross-sell accessories or other related products.
Advanced¶
The following section includes examples of more advanced panel structures.
Backfill complete panel¶
A zone will omit any sub-panel that is empty in a result. When for example performing a panel split test, there may be a need to have a backfill panel if there is a risk that none of the competing panels return products.
A method to enable this is to create a zone and set it to As in hierarchy with Maximum number of subpanels set to 1. This zone will in turn contain a zone using Panel split test with two competing panels in it and a panel for backfill. The panel for backfill will only be returned if the competing zone returns an empty result.
Before configuring a panel split test, it is recommended to contact Voyado Support.
