Pular para o conteúdo principal

​
Prerequisites

  • VTEX IO CLI (vtex) installed and authenticated
  • VTEX store on IO framework
  • Alana API key (search-only key from workspace settings)
  • vtex.search-resolver@0.x must NOT be installed — the Alana resolver conflicts with VTEX’s native search resolver

​
Conflict Check

Before installing, verify that vtex.search-resolver@0.x is not active: 
vtex ls | grep search-resolver
If it appears in the output, uninstall it first: 
vtex uninstall vtex.search-resolver@0.x

​
Installation

vtex install alana.search-resolver@0.x

​
Configuration

After installation, configure your API credentials via the VTEX Admin panel:
  1. Go to Apps → My Apps → Alana Search Resolver
  2. Set Alana API Key (required) — your ak_xxx key
  3. Set Alana API URL (optional) — defaults to https://app.alana.shopping
  4. Save and wait ~30 seconds for propagation
Or configure via CLI: 
vtex settings set alana.search-resolver alanaApiKey "ak_your_api_key"
vtex settings set alana.search-resolver alanaApiUrl "https://app.alana.shopping"

​
Resolver Mapping

The Alana app implements the VTEX Search Protocol GraphQL resolvers and proxies them to the Alana Search API v1:
VTEX ResolverAlana EndpointNotes
productSearchPOST /api/v1/searchfrom/to mapped to page/hitsPerPage
facetsPOST /api/v1/searchhitsPerPage: 0 — facets only
autocompleteSearchSuggestionsGET /api/v1/autocompletelimit: 10
searchSuggestionsGET /api/v1/autocompletelimit: 5 with product previews
topSearchesGET /api/v1/searchReturns trending queries
correctionPOST /api/v1/searchhitsPerPage: 0 — extracts correctedQuery

​
OrderBy Mapping

VTEX OrderBy strings are automatically translated to Alana sort values:
VTEX OrderByAlana sortBy
OrderByTopSaleDESCrelevance
OrderByReleaseDateDESCnewest
OrderByBestDiscountDESCrelevance
OrderByPriceDESCprice_desc
OrderByPriceASCprice_asc
(all others)relevance

​
Caching

@cacheControl directives are set per resolver:
ResolverTTL
productSearch, facets120 s
autocompleteSearchSuggestions, searchSuggestions60 s
topSearches300 s
correction120 s

​
Troubleshooting

Search returns empty results
  • Verify the API key is set in App Settings
  • Check that the catalog has been indexed (Workspace → Products → Sync)
vtex.search-resolver@0.x conflict error
  • Uninstall the native resolver before installing Alana: vtex uninstall vtex.search-resolver@0.x
Resolver returns 401
  • The API key in App Settings is incorrect or expired
  • Generate a new search-only API key in Alana workspace settings
Facets are empty
  • Ensure facet configs have been created via /api/v1/facets/config for your workspace
Last modified on March 12, 2026