Wearly
Wearly
Documentation

VTEX Integration

Integrate Wearly's AI-powered search technology with your VTEX store.

Overview

Wearly offers a seamless integration with VTEX, allowing you to enhance your e-commerce platform with our AI-powered search technology. This integration enables your customers to find products more efficiently using natural language queries and receive highly relevant results.

Integration Benefits

  • ✓Replace VTEX's default search with Wearly's AI-powered search
  • ✓Natural language understanding for complex queries
  • ✓Automatic product catalog synchronization
  • ✓Real-time inventory and pricing updates
  • ✓Personalized search results based on user behavior

Integration Methods

API Integration

Use our REST APIs to create a custom integration with your VTEX store.

JavaScript SDK

Implement our JavaScript SDK for client-side integration with your VTEX theme.

GraphQL Implementation

Implement the VTEX Search Protocol using GraphQL queries for seamless integration.

Search Protocol

The Search Protocol defines the contract between an external search provider (Wearly) and a VTEX store running on VTEX IO. By adhering to this protocol, Wearly can replace completely the original VTEX search capabilities without needing to implement any frontend pages or React components.

The main idea is to provide the ability for Wearly to integrate with the minimum amount of work necessary and for a VTEX customer to easily switch to Wearly's search provider without having to change anything in the storefront.

How the Search Protocol Works

1

GraphQL Implementation

Wearly implements resolvers for every GraphQL query on the vtex.search-graphql schema, allowing seamless integration with the VTEX storefront.

2

Catalog Indexing

Wearly sets up webhooks to receive notifications whenever a change in the catalog occurs, ensuring that the search index is always up-to-date.

3

Search Processing

When a user performs a search, the query is processed by Wearly's AI engine, which understands natural language and returns highly relevant results.

4

Seamless Integration

The results are returned in the format expected by the VTEX storefront, ensuring a seamless experience for both the store owner and the end user.

Specification

To implement the VTEX Search Protocol, Wearly implements resolvers for specific GraphQL queries on the vtex.search-graphql schema.

GraphQL Queries Implemented

Wearly implements the following GraphQL queries to provide a complete search experience:

  • productSearch

    The actual search engine query that returns product results based on search terms.

  • facets

    Facets to be used as filters in the search results page.

  • banners

    Banners to retrieve and show in specific sections of the web page.

  • correction

    Corrections for possible typos that a user makes when searching for a product.

  • searchSuggestions

    Suggestions of terms based on the search term that the user has made.

  • topSearches

    Top searches that are shown when a user puts the cursor over the search bar.

  • autocompleteSearchSuggestions

    Suggestions of products and terms to be shown in the search bar.

  • productSuggestions

    Suggestions of products to be shown in the search result page.

  • searchMetadata

    Metadata for the specific search result page.

GraphQL Queries Not Reimplemented

The following queries are not reimplemented by Wearly, as they don't add anything potentially beneficial to the UX. Instead, Wearly leverages the VTEX Catalog API's to implement them:

  • • product
  • • products
  • • productsByIdentifier
  • • searchURLsCount

Indexing

Wearly sets up webhooks to receive notifications whenever a change in the catalog occurs. This ensures that the search index is always up-to-date with the latest product information.

The indexing process works as follows:

  1. 1.When a product is created, updated, or deleted in VTEX, a webhook notification is sent to Wearly.
  2. 2.Wearly processes the notification and updates its search index accordingly.
  3. 3.The updated index is immediately available for search queries, ensuring that users always see the most up-to-date product information.

Onboarding

When a user integrates Wearly with their VTEX store, an onboarding process is required to set up the integration and index the product catalog.

Onboarding Flow

  1. 1.VTEX client contacts Wearly to initiate the integration process.
  2. 2.Wearly provides access to an admin panel to set up the integration.
  3. 3.The admin panel notifies Wearly's indexing system that a new account is to be indexed.
  4. 4.Wearly indexes the entire product catalog, which can be monitored through the admin panel.
  5. 5.Once indexing is 100% complete, the VTEX client can fully enable Wearly's search functionality.

Limitations

There are a few limitations to be aware of when integrating Wearly with VTEX:

  • •It is only possible to have one search-resolver service per workspace. If more than one is installed, the workspace will break. This is a known issue that VTEX plans to solve in the future.
  • •The 4 queries listed above that are not reimplemented are still indeed needed to be implemented. Wearly handles this by leveraging the VTEX Catalog API's for these queries.

Search Implementation Examples

Here are some examples of how Wearly's search implementation works with VTEX:

Example: Product Search Query

This is an example of how Wearly implements the productSearch GraphQL query:

// Example GraphQL query for product search
query productSearch(
  $query: String,
  $map: String,
  $fullText: String,
  $selectedFacets: [SelectedFacetInput],
  $from: Int,
  $to: Int,
  $orderBy: String
) {
  productSearch(
    query: $query,
    map: $map,
    fullText: $fullText,
    selectedFacets: $selectedFacets,
    from: $from,
    to: $to,
    orderBy: $orderBy
  ) {
    products {
      productId
      productName
      linkText
      description
      brand
      brandId
      link
      items {
        itemId
        name
        nameComplete
        complementName
        ean
        referenceId {
          Key
          Value
        }
        images {
          imageId
          imageLabel
          imageTag
          imageUrl
          imageText
        }
        sellers {
          sellerId
          sellerName
          commertialOffer {
            Price
            ListPrice
            AvailableQuantity
          }
        }
      }
    }
    recordsFiltered
    breadcrumb {
      name
      href
    }
  }
}

Example: Facets Query

This is an example of how Wearly implements the facets GraphQL query:

// Example GraphQL query for facets
query facets(
  $query: String,
  $map: String,
  $fullText: String,
  $selectedFacets: [SelectedFacetInput],
  $operator: Operator,
  $behavior: String,
  $from: Int,
  $to: Int
) {
  facets(
    query: $query,
    map: $map,
    fullText: $fullText,
    selectedFacets: $selectedFacets,
    operator: $operator,
    behavior: $behavior,
    from: $from,
    to: $to
  ) {
    breadcrumb {
      name
      href
    }
    facets {
      name
      type
      values {
        id
        name
        quantity
        selected
        link
        value
      }
    }
  }
}