Personalizing the Search Experience

One of the premier use cases for Search Experiences and Search Blueprints is to personalize Liferay’s search results. With a personalized search experience, each user sees results depending on the particular details of his or her context. There are currently Elements for making your Blueprint react to the answers of contextual questions like

• Where is the user?
• What roles does the user have?
• What sites is the user a member of?
• What content does the user own?
• Is the user a Guest?
• Is the user a new user?
• What User Segments is the user part of?

Without a Blueprint tailored for each user’s context, the default results are scored based on a query that calculates relevance by how well the text of the searched keywords matches the tokenized values of indexed documents.

Personalizing search results increases the chance that users find what’s needed for their success. This in turn increases the chance of your site’s success, by keeping users engaged with your content. Some examples include

• Prioritizing certain results if they are near in proximity to the user’s IP Address
• Prioritizing certain content if the user is new
• Hiding certain content if the user isn’t authenticated

Personalization Elements

There are several Elements that are especially useful for personalization efforts:

Boost Proximity: uses the ipstack service to boost search results closer to a user’s location, as marked by a geopoint field in the document. The example below shows you how to set up the service and use the Boost Proximity Element.

Boost Contents for the Current Language: boosts search results with a defaultLanguageId field matching the current session’s language.

Hide Contents in a Category for Guest Users: hides search results matching with a certain category field, if the search user is unauthenticated.

Limit Search to My Contents: only returns search results if the document’s userId field matches the search user.

Limit Search to My Sites: only returns search results scoped to a site that the user is a member of.

Boost Contents on My Sites: boosts search results if the search user is a member of the site the results are scoped to.

Boost Contents in a Category for New User Accounts: boosts search results with a certain category if the search user’s account was created in a certain time range.

Boost Contents in a Category for a User Segment: boosts search results with a certain category if the user belongs to a certain User Segment.

Building a Blueprint to Personalize Search Results

Sometimes, you may want to present results based on the user’s location. To do this, you must

• Configure the service that geolocates the User’s IP address, https://ipstack.com.
• Geolocate a Liferay Asset.
• Create the Blueprint with the Element that communicates with the geolocation service.

Configure the Ipstack Service

Before configuring the Blueprint, you must obtain an ipstack key and enable the ipstack service in Liferay.

1. Go to https://ipstack.com and obtain an API key.
2. In Liferay, go to System Settings → Platform → Search Experiences → Ipstack.
3. Click Enabled.
4. Enter the API Key.
5. Click Save.

Configure a Geolocated Asset

A search document must have a geopoint field to work with the ipstack service and the Boost Proximity Element. Liferay includes compatible Geolocation fields that you can add as a Custom Field to existing assets:

1. Go to Control Panel → Custom Fields.
2. Add a new Custom Field on the Blogs Entry:
   • Type: Geolocation
   • Field Name: location
3. Click Save.
4. Add two new blogs entries (open the Site Menu and go to Content & Data → Blogs):
   • First Blogs Entry
     • Title: Blog title
     • Content: Blog content
     • Under Custom Fields, drag the geolocation pin somewhere approximately 100 km from your current location.
     • Publish the blog.
   • Second Blogs Entry
     • Title: Second blog title
     • Content: Second blog content
     • Under Custom Fields, drag the geolocation pin as close as possible to your current location.
     • Publish the blog.

tip

Zoom into the geolocation map in order to place the pin more precisely.

Search for the word blog on the search page. The blogs entry with the shorter title and content fields (the first one, titled Blog title) appears first in the Search Results widget.

Configure a Geolocation-Aware Blueprint

Now that you have the ipstack service configured and search documents with geopoint data, you’re ready to configure a Blueprint that boosts certain results by their proximity to the search user:

1. Open the Blueprints application by clicking Blueprints from Global Menu → Applications (Search Experiences).

2. Add a Blueprint by clicking Add ().

   

3. In the New Search Blueprint window, give the Blueprint a name (required) and a description (optional).

4. Use the Query Builder to add the Boost Proximity Element.

   • Set the field as expando__keyword__custom_fields__location_geolocation.
   • Set the Decay to 0.8.
   • Set the Scale to 10 km.
   • Set the Boost value to 100.

   

5. Test the Blueprint as you build and configure it. Click Preview.

6. To model the search experience of a user in your location, click the gear icon () to set your public IPV4 address into the search context.

   • Key: search.experiences.ip.address
   • Value: [My Public IPV4 Address]

   Click Done.

7. Enter the keyword blog and verify that the geolocated blogs entry that’s closer to your location is returned before the more distant blogs entry.

8. Once you’re finished with the Blueprint, Click Save.

Now you can apply the Blueprint to a Liferay search page.

You might need to adjust the Gaussian function that scores documents by proximity to the sending IP address:

Decay defines the factor by which to reduce the boost value when the proximity of the asset to the user is equal to the scale.

Scale is the distance away from the user’s IP address location, above which the relevance of results should begin to deteriorate.

Boost is the numeric value to boost results within the defined scale.

For example, if you specify a boost of 100 for search results geolocated to within 10 km of the user and define a decay factor of 0.5, a result exactly 10 km away from the user receives half of the maximum boost value, so it is boosted by 50. At distances greater than 10 km, the Gaussian function takes over in determining the remaining scores.

See Elastic’s Function Score Query documentation for more details.