Skip to main content

​
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:
If it appears in the output, uninstall it first:

​
Installation

​
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:

​
Resolver Mapping

The Alana app implements the VTEX Search Protocol GraphQL resolvers and proxies them to the Alana Search API v1:

​
OrderBy Mapping

VTEX OrderBy strings are automatically translated to Alana sort values:

​
Caching

@cacheControl directives are set per resolver:

​
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
Última modificação em 12 de março de 2026