Using Automatic Boosting
Automatic Boosting is a feature that can help you personalize your search components by leveraging information coming from your user profiles and patterns. It automatically boosts search results according to the visitor pattern.
This tutorial assumes that:
You have a running Sitecore instance with DMS or xDB installed.
You have the Enterprise edition of Coveo for Sitecore.
You have read and understood the page Understanding Profiles and Pattern Cards.
You have indexed documents with the parameter
true(see Understanding the Coveo Search Provider’s Configuration File).
Using the Automatic Boosting requires that you have defined Profiles, Profile Cards, and Pattern Cards in your Sitecore instance. Remember to set the minimum and maximum values on every profile key. Items should also have Profile Cards assigned to them if you want them to be boosted.
Enabling Automatic Boosting Using the Coveo for Sitecore Hive UI Framework
To enable automatic boosting
Open your Coveo-powered search page in the Sitecore Experience Editor.
Select the UI Header placeholder.
Click + Add here.
Select the Automatic Boosting rendering.
In the Select the Associated Content dialog, select Create New Content.
Give your data source a name and save it in an appropriate location in your data source branching.
In the Automatic Boosting component floating toolbar, select the Edit the rendering’s data source option. It should be the leftmost option.
In the Query Ranking section, select Enable automatic boosting. Options will appear under the Enable automatic boosting check box.
Select any of the options that appear under the Enable automatic boosting check box. In this example, the
Focusoption is selected.
Click OK in the dialog to accept the default boosting settings.
Save the changes to your search page in the Experience Editor.
Understanding How It Works
Automatic Boosting generates a Query Ranking Function (QRF) in your queries based on the current visitor pattern.
For example, the current visitor pattern identified for the Visit Profile profile is called Bob the businesstraveler, and is defined as such:
To understand how it works, remember that patterns are a combination of profile keys. The QRF is based on those profile keys.
The generated QRF uses the profile keys percentage value. For example, the value of the Bob the business traveler pattern for the Duration profile key is 8 out of 10, so the percent value is 0.8 (80%).
Every item with a Duration profile key with a percentage value close or equal to 0.8 will be boosted. The closer they are, the more they’re boosted.
The boosting is done following a Gaussian (bell shaped) function that you can adapt with the different settings.
The following graph is an example of what the function looks like for the Duration profile key with the default settings:
Looking at the graph, you can see that an item with a Duration profile key percentage of 0.8 would be boosted by 80 points (see Boosting Settings below to understand how the maximum value, in this case 80, is calculated).
Items with 0.7 or 0.9 would be boosted by approximately 48 points, items with 0.6 or 1 would be boosted by approximately 11 points, and items with further values would’nt be boosted significantly.
A graph like this is applied to each profile key and the results are added together in the QRF. Here is an example of a full QRF generated by the Bob the business traveler pattern card:
$qrf(expression:'exp(-(@fvisitz32xprofilez32xbusinessz32xkeyz32xpercent93146-1)^2/(2*0.01))*150 + exp(-(@fvisitz32xprofilez32xcouplesz32xkeyz32xpercent93146-0.1)^2/(2*0.01))*10 + exp(-(@fvisitz32xprofilez32xdurationz32xkeyz32xpercent93146-0.8)^2/(2*0.01))*80 + exp(-(@fvisitz32xprofilez32xnightlifez32xkeyz32xpercent93146-0.4)^2/(2*0.01))*40 + exp(-(@fvisitz32xprofilez32xrepeatz32xvisitsz32xkeyz32xpercent93146-0.1)^2/(2*0.01))*10 + exp(-(@fvisitz32xprofilez32xtourismz32xkeyz32xpercent93146-0.2)^2/(2*0.01))*20', normalizeWeight: True)
You can see each profile key that isn’t zero in the pattern card represented in the QRF.
You can also see the
normalizeWeight parameter at the end of the equation. This is always true, as it prevents boosting from being too small or too big. More specifically, it maps the complete value domain to the
Three settings are available to help fine-tune your automatic boosting.
Boosting Influence (%)
This setting is used to calculate the maximum value of the boosting on a profile key (maximum value = Profile key percentage x Boosting Influence). This explains the 80 in the example above.
However, since the values are normalized, the setting doesn’t change anything if you only have one profile enabled.
This setting is useful if you activate more than one profile, and want one of them to have more influence on the boosting. For example, if you have Visit Profile and Score enabled, but you want Visit Profile to be more important, you can let the Boosting Influence of Visit Profile at 100, but put the Boosting Influence of Score at 50. That way, the boosting influence from the Visit Profile will be twice as important as the one from Score.
Boosting Weight Range
This is an important setting to customize, as the default value isn’t ideal for every situation.
This setting allows you to be more or less restrictive about the boosting. A larger value allows you to boost profile keys with percentages further from the pattern, and a smaller value makes your boosting affect only items with the exact same profile key percentage as the pattern. This affects the width of the graph.
Using the same example as above, you can change the Boosting Weight Range to 2, making the graph look like this:
Here, a profile key with a percentage value of 0.8 would still be boosted by 80 points, but 0.7 and 0.9 would now be boosted by approximately 62 points, 0.6 and 1 by approximately 29 points. A percentage value of 0.5 would now yield 8 points.
You could also narrow it if you only want 0.8 to be boosted by changing the value to 0.01, making the graph look like this:
It’s possible to test and see the look of the function with different values for the Boosting Weight Range. To see the equation used to draw the graphs for the previous example, see the Wolfram|Alpha diagram.
By editing some values, you can adapt it to your situation and see what the graphs look like. Here is the equation you should see:
plot exp(-(x-0.8)^2/(2*1/100))*80 x from 0 to 1 y from 0 to 80
Here are the values to edit:
The 0.8 is the profile key percentage value from your pattern card. Be sure to modify the maximum value if you edit this to have coherent results.
The 1 in the equation is the Boosting Weight Range.
The 80 in the equation is the maximum value. It should always be equal to the profile key percentage value x Boosting influence.
The x from 0 to 1 y from 0 to 80 section is simply a display setting. Modifying the maximum value of the y parameter to fit the maximum value allows you to see the complete graph.
Dominant Keys Boosting Influence (%)
The dominant key of a pattern is the profile key with the highest value, and with a percent value of at least 0.5. The Dominant Key Boosting Influence increases the maximum boost value of the dominant profile key by the amount specified. Its default value is 50%.
For example, when looking at the Bob the business traveler pattern above, you can see that the dominant profile key is Business. Normally, the maximum value would be 100 (1 * Boosting Influence), but you can see in the QRF that the maximum value is 150. That’s because a 50% boost was added (100 + 100 * 50% = 150).
Testing the Automatic Boosting
You may notice that enabling Automatic Boosting doesn’t change anything in your search results ranking. This is most likely because Sitecore has not recognized any visitor pattern yet. A visitor pattern is recognized when visiting pages that correspond to an item with an assigned profile card.
The fastest way to test your automatic boosting is to use the Experience Explorer (see Using the Experience Explorer).
Remember to publish your search page or search component before using it.
In this example, the Business item was clicked a few times, and Sitecore recognized the pattern Bob the business traveler. With the automatic boosting, the item with the Business profile appears first.
The generated QRF is based on the pattern card item (Bob the business traveler in that case) and not on the values that you see on the Viewer tab. The Viewer tab simply tells you the keys that have been calculated, but the real pattern is the card itself.
Gathering the Ranking Information on Results
If you want more information on the ranking of each result in your result template, you can add
&debug=1 at the end of the URL of the search page, before the
# if you had done a query.
Then, when opening your browser developer console, you should see the details of the ranking generated for each result: