Once your Searchspring API integration has its core functionality completed it is now safe to begin creating custom merchandising for specific pages. This document will walkthrough the steps needed to ensure there are no issues when creating a campaign that will display results within the Autocomplete Module, for a Search results page, or for a Category page.

Core functionality:

Identify a page to create a campaign for

Before creating a merchandising campaign you will need to first identify the page you would like to create a merchandising campaign for. Once the page is identified you will need to source the Searchspring API endpoint that is powering the results for the page and collect all relevant contextual data that is currently refining results for that page. Query string parameters that handle result refinement are (q), (bgfilter), or (filter).

Let's say we would like to create a merchandising campaign for the page https://bocachica.searchspring.com/collections/womens-pants. Using the browsers Network panel we can filter the Network logs by search.json to find the API endpoint that is called for the page.

Refresh the page and then click the most relevant resulting resource and then click the payload tab so we can review the Query string parameters.

Here we can see for the API request that is called to power the results on the page a background filter parameter is being passed to tell the API to only return results that have a field of collection_handle with a value of womens-pants.

Now we have what we call the contextual data we can create a merchandising campaign that will be triggered on this page.

Create a campaign

You can now log into your Searchspring account and navigate to the Visual Merchandiser tool to create a campaign. To create a campaign click the box shown to the right 'Create a Campaign'. Because you are creating a campaign for a category page you will select the 'Category' option. Next you will set the filter based on the contextual data retrieved from the API endpoint. In this case the contextual data is collection_handle and womens-pants. The first dropdown will represent the field (collection_handle) and the second dropdown will represent the value (womens-pants). Once the contextual data is set click 'Start Merchandising'.

On the next page set a specific title for the campaign, click the 'Save' tab, then click 'Save and Publish'.

Triggering a Merchandising Campaign

Now these changes are saved you can verify if the contextual data that was set for the campaign is correct or not by navigating back to the page on the site, wait for 5mins for the browsers cache to clear, refresh the page, and then review the new API endpoints response data by clicking on the 'Preview' tab in the Network panel.

If the contextual data is matched we should see data returned in the API response within the merchandising.triggeredCampaign object that indicates the configured campaign was triggered and the data returned is sourced from the campaign.

Below is a snippet that showcases how this would look in the API response

{
  "pagination": {...},
  "sorting": {...},
  "resultLayout": "grid",
  "results": [...],
  "facets": [...],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {...},
    "facets": [...],
    "facetsHide": [],
    "experiments": [],
    "variants": [],
    "personalized": false,
    "triggeredCampaigns": [
      {
        "id": "98908",
        "title": "Womens Pants",
        "type": "filter"
      }
    ]
  }
}

Documentation:

Once a merchandising campaign is triggered in the Autocomplete or Search API response, you can begin making configuration changes in the campaign to build the merchandising experience for the page. Note that this is just the beginning, features found on the Standard Merchandising and Advanced Merchandising pages will need to be implemented as well in the integration.