Promotions

Updated

Use Promotions in SearchStax Site Search to feature important content when a search matches a keyword or phrase. Promotions can highlight indexed pages or display links to external content for campaigns, seasonal events, and high-priority topics.

Promotions are configured at the Search Profile level. For an overview of this scope, see Search Profiles. You can also watch the Promotions video for a brief demonstration.

How Promotions Work

A promotion has one or more trigger phrases and one or more promoted items. When a search matches a trigger, Site Search displays the promotion.

  • Indexed promotions feature documents from your App's search index. They appear at the top of the regular results, below any external promotion that is also displayed.
  • External promotions display banner-style links above the regular search results. They can point to webpages outside your index.

You can include indexed and external items in the same promotion. See Promotions: Indexed vs. External for a comparison of their appearance and behavior.

How Promotions Interact with Other Features

Other Search Profile settings can affect which results appear. For example, Data Filters can exclude an indexed document even when it is included in a promotion. Ranking, Rules, and Smart Ranking also affect the search experience. Smart Ranking reorders standard results while leaving promotions at the top.

If a promotion doesn't appear as expected, check the trigger, publication state, indexed item, and active filters before changing other relevance settings.

Promotions and Smart Answers

When Smart Answers is enabled, it can prioritize matching indexed promotions as sources for generated answers. If no matching indexed promotion is available, it can use its other configured content sources.

External promotions are links, not indexed document sources, so they aren't prioritized in the same way.

Create a Promotion

Add Trigger Phrases

  1. Open the Search App and Search Profile you want to configure.
  2. Go to Optimizations > Promotions.
  3. Select Create New Promotion.
  4. Add a keyword or phrase as a trigger. Use the plus (+) control to add more triggers. A promotion can activate when any one of its triggers matches.
  5. For each trigger, select a matching option:
  • Exact Match: The search query must match the configured trigger exactly.
  • Contains: The search query can contain additional words, but the trigger must match as a whole word or phrase. Contains does not automatically apply stemming, substring matching, or regular expressions.

For example, a Contains trigger of pension matches pension advice, but not pensions. Add any plural or other word variations you need as separate triggers.

Promotion Details showing two trigger phrases with Contains match options and an add-trigger control.

Add Indexed Items

Use indexed items when the content you want to feature already exists in your App's search index.

  1. Under Promotion Definition, select Indexed Items.
  2. Use Default search to find a document by keyword or phrase. For a specific field or value, use Advanced Search as described below.
  3. Select up to 10 indexed items from the Indexed Items Pool to promote.
  4. Use Move Up and Move Down to arrange the promoted items in the desired order.

Indexed Items Pool with selectable search results and the Promoted Items list with ordering controls.

Note: Indexed promotions require documents that are currently in the search index. If a page isn't available in the pool, confirm that it was indexed and try searching for its indexed field values.

Find an Indexed Item with Advanced Search

Advanced Search uses Solr field:value syntax. Use field names from your App's index. For example, an App might store a page URL in a field named resulturl_s rather than url.

These examples illustrate the syntax. Field names and values depend on your App's index:

  • id:"ed55498c-1f34-395d-963f-c79e1679ffee"
  • url:"https://www.searchstax.com/docs/searchstax-cloud-solr-backups/"
  • year_published:2022

If a query returns no items, check the indexed field name and value, try a simpler query, and confirm the document is indexed. Before adding an item to a promotion, check that the result is the intended indexed document.

Advanced Search in Indexed Items showing a URL-field query, matching results, and the Promoted Items area.

Add External Items

Use an external item to display a banner-style link above search results. The destination can be a page in your search index or another URL.

  1. Open the promotion's External Items tab.
  2. Select Create.
  3. Enter a Title, an optional Description, and the destination URL. Use a unique URL for each external promotion.
  4. Select the external item from External Items Pool to add it to External Items Results.
  5. Save the promotion as a draft or publish it when you're ready to make the change active.

External Items tab with Create button and empty External Items Results container for adding promotion items.

External item creation form with title, description, and URL fields for a Sitecore/Solr compatibility resource.

Save, Publish, and Manage Promotions

Use Save Draft to keep promotion changes without making them active. Select Publish when you're ready for your changes to take effect in the live search experience.

Review Promotion Statuses and Missing Items

  • Enabled: The promotion is enabled in its configuration. Unpublished changes do not affect the live search experience.
  • Disabled: The promotion is turned off in its configuration.
  • Missing: An enabled promotion references one or more indexed items that are no longer present in the search index.

Open Promotion Details to review any missing-item warnings and identify indexed items that need attention. A missing-item warning doesn't prevent you from saving or publishing the promotion, but the missing item won't appear as intended. Replace or remove outdated items before publishing when possible.

  1. Open the affected promotion and inspect its linked indexed items.
  2. Replace or remove an outdated reference. If you can't find a replacement, confirm that the intended page is in the index.
  3. Select Save Draft to keep your changes, and Publish when the corrected promotion is ready.

Promotions table showing Enabled and Missing status labels, including a Drupal promotion marked Missing.

Publish to Multiple Profiles

If your App has multiple Search Profiles, use Publish to Profile(s) to select the profiles that should receive your promotion changes. Confirm your selections before publishing.

Publish to Profile(s) dialog showing options to select search profiles for applying promotion changes.

Best Practices

  • Use descriptive promotion names so you can recognize and manage campaigns.
  • Review promotions periodically. Update, disable, or remove promotions that are no longer relevant.
  • Use Advanced Search with verified indexed fields when the default item search doesn't find the document.
  • Check active Data Filters and publication state when a promotion doesn't appear as expected.

Examples and Troubleshooting

For practical examples, see Curate Your Site Search Experience (indexed promotions) and Improve the Search Experience with External Promotions.

For problems with trigger matching, indexing, filters, draft state, or missing items, see Troubleshooting Promotions.

Articles in this section