Documentação do módulo Nuxt

Visão geral

O storefront da Uappi é uma aplicação Nuxt 2, então a integração é um módulo Nuxt e não um <script>: o tema instala o pacote @rocketsearch/nuxt-uappi, registra o módulo e usa os componentes onde quiser. As funcionalidades são as mesmas do SDK Linx 2.0.0.

Requisitos

• Nuxt 2.15 ou superior e Vue 2.7.
• Módulo @nuxtjs/axios com o baseURL apontando para a API da Uappi (o padrão dos temas Uappi).
• Domínio da loja liberado no painel da Rocket Search para a API Key usada.

Instalação

npm install @rocketsearch/nuxt-uappi

Registre o módulo em nuxt.config.js:

modules: [
  '@nuxtjs/axios',
  ['@rocketsearch/nuxt-uappi', {
    storeId: 'minha-loja',
    apiKey: 'pk_live_xxxxxxxxxxxx',
    uappiDomain: 'loja.minhaloja.com.br'
  }]
]

Pronto — com isso a loja já tem analytics rodando. Os componentes são registrados automaticamente; não é preciso importar nada.

Configuração

As opções vão no segundo item do array do módulo, ou numa chave rocketSearch na raiz do nuxt.config.js.

Opções do módulo

Busca e Autocomplete

<RocketAutocomplete>

Substitui o campo de busca do header. Sugere termos e produtos enquanto o cliente digita; com o campo vazio, mostra os termos mais buscados. Enter ou o botão levam à página de busca.

<RocketAutocomplete input-placeholder="O que você procura?" :products-limit="4" />

<RocketSearch>

A página de busca completa. Lê o termo da URL (?busca=), mantém filtros, ordenação e página na URL e funciona com voltar/avançar do navegador. Crie uma view para a rota de busca do tema e coloque o componente nela:

<RocketSearch :page-size="24" facets-mode="side" />

Modo categoria

Com is-category, a página lista a categoria em vez de um termo, com as mesmas facetas e ordenação. O id é o da categoria na Uappi:

<RocketSearch is-category :category-id="$store.state.dadosPageAtual.conteudo.id" />

Usando o card do tema

A grade vem com um card simples. Para manter o card da loja (preço, selos, botão de compra), use o slot #product — ele recebe o produto no formato da Uappi. O mesmo slot existe na vitrine.

<RocketSearch>
  <template #product="{ product }">
    <CommonProductCard :product="product" />
  </template>
</RocketSearch>

Mantendo a listagem do tema

Se o tema já tem a própria página de listagem (filtros laterais, ordenação, paginação) e a loja quer manter esse visual, dá para trocar só a fonte dos dados: rocketSearchListing busca na Rocket e devolve a resposta no mesmo formato da Front API da Uappi (/v2/front/url/product/listing/search). O resto do tema continua igual.

import {
  rocketSearchListing,
  dispatchListingSearch,
  dispatchListingClick
} from '@rocketsearch/nuxt-uappi/runtime/listing.js';

// No lugar do GET da listagem, quando a rota for a de busca:
const data = await rocketSearchListing({
  $rocket: this.$rocket,
  $axios: this.$axios,
  query: this.$route.query,   // busca, pg, ipp, order, preco + facetas
  limit: 12,                  // itens por página quando não há ?ipp
  titleSuffix: ' | Minha Loja'
});

// Evento de busca: no cliente, depois de montar a página (no SSR ele não sai)
dispatchListingSearch(this.$rocket, data);

// Clique num card da grade
dispatchListingClick(this.$rocket, data, product, index);

A URL segue o vocabulário da listagem da Uappi: busca, pg, ipp, order (id da ordenação da Rocket) e preco=min-max. As facetas entram como ?BTUs=9.000;12.000. Os filtros nativos da Uappi (marca, filtro, atributo, selo) e os parâmetros de campanha (utm_*, gclid…) são ignorados, para que um link antigo não zere a busca.

Vitrines

As vitrines são cadastradas no painel com um tipo de página (home, produto, categoria, busca) e uma posição. O componente mostra a vitrine daquela posição na página atual; sem vitrine cadastrada, não renderiza nada.

<RocketShowcase>

<RocketShowcase position="top" />
<RocketShowcase position="middle" />
<RocketShowcase position="bottom" />

O tipo de página vem do tema (dadosPageAtual): na home busca as vitrines da home, na página de produto as de produto, e assim por diante. Todas as vitrines da página saem de uma única chamada à API.

Props e slots

Para a vitrine da Rocket sair com o carrossel e o título do próprio tema, use o slot padrão:

<RocketShowcase position="top">
  <template #default="{ showcase, products }">
    <CommonShowcase :title="showcase.name" :data="{ produtos: products }" />
  </template>
</RocketShowcase>

O clique continua medido: o componente reconhece o produto pelo link do card, qualquer que seja o markup do tema. O wrapper tem margem vertical de 60px; zere com uma classe própria se o componente do tema já trouxer o espaçamento.

Colunas no desktop e no mobile seguem o layout cadastrado no painel. Se a vitrine tiver um banner vinculado, ele aparece acima dos produtos; um banner cadastrado sozinho numa posição de vitrine aparece no lugar dela.

Banners

Banners cadastrados no painel, com imagem desktop e mobile, link, texto opcional e teste A/B.

<RocketBanner>

<!-- Banner principal: já vem no HTML, com carrossel se houver mais de um -->
<RocketBanner position="hero" loading="ssr" carousel />

<!-- Banner do meio da página: só carrega quando chega perto da tela -->
<RocketBanner position="middle" ratio="4/1" />

loading: ssr ou ondemand

Props

Imagens responsivas

• A imagem mobile do painel é usada em telas de até 768px.
• No modo ondemand, a imagem é pedida na largura exata do espaço (considerando a densidade da tela). No ssr, vai com várias larguras e o navegador escolhe.
• O primeiro banner da posição hero carrega com prioridade alta; os demais, só quando estão para aparecer.
• Se o redimensionamento falhar para uma imagem, o banner usa a imagem original em vez de sumir.

Métricas

Impressão e clique são enviados automaticamente. A impressão só conta quando o banner fica pelo menos metade visível por 1 segundo; o clique registra a posição relativa na imagem, que alimenta o mapa de calor do painel.

Link interno navega sem recarregar a página. Link externo espera o evento ser enviado antes de sair.

API JavaScript

O módulo injeta $rocket no contexto do Nuxt: this.$rocket nos componentes e context.$rocket em asyncData, fetch, middlewares e plugins.

this.$rocket

// Busca simples
const data = await this.$rocket.search({ q: 'split', page: 1 });
console.log(data.total, data.products); // produtos com id e preço; o resto vem da Uappi

// Vitrines da home
const showcases = await this.$rocket.getShowcasesByContext('home');

Eventos dos componentes

Use o @products-loaded da busca para alimentar o SEO e o GTM do tema, que leem dadosPageAtual:

<RocketSearch @products-loaded="onProductsLoaded" />

onProductsLoaded ({ products, term }) {
  this.$store.commit('setDadosPageAtual', {
    estrutura: { nivel: 'product/listing/search', seo: { title: term, indexar: false } },
    conteudo: { produtos: products }
  });
}

Analytics

Só de registrar o módulo, visualização de produto, navegação e carrinho já são rastreados. Os componentes rastreiam busca, clique e impressão sozinhos.

Eventos automáticos

dispatchEvent()

Para eventos que o módulo não cobre:

this.$rocket.dispatchEvent('click', {
  productId: '391',
  meta: { source: 'minha-vitrine' }
});

Sessão, tipo de página e origem da visita são adicionados automaticamente.

Checkout: login e compra

O checkout da Uappi roda fora da aplicação Nuxt, então o login feito ali e o purchase saem por uma tag do GTM. Crie uma tag HTML personalizado com dois acionadores: Visualização de página com Page Path contém /checkout, e Evento personalizado = purchase.

<script src="https://api.rocketsearch.com.br/sdk/uappi/rocket-checkout.js"
        data-store-id="minha-loja" data-api-key="pk_live_..."></script>

• Login: a cada página do checkout, o script consulta a API do front da Uappi (checkout/user) e envia o login uma vez por sessão. Login já enviado pelo módulo na loja não sai de novo.
• Compra: lê o purchase que a Uappi envia ao dataLayer na confirmação (transaction_id, value, items) e liga a compra à sessão e às vitrines gravadas pelo módulo. Recarregar a confirmação não envia de novo.

Os dois acionadores disparam juntos na confirmação; o script não duplica nada. data-debug="true" loga os eventos no console.

CSS

Cada componente traz o próprio CSS, com classes prefixadas por rocket-search__. As cores seguem variáveis que o tema pode sobrescrever no próprio CSS:

.rocket-search {
  --primary-color: #0a4ea2;
  --secondary-color: #e30613;
}

Debug e Troubleshooting

Modo debug

• debug: true no módulo loga no console cada evento enviado.
• ?rocket-search-debug=true na URL destaca vitrines e banners da Rocket na página por 1 hora; =false desliga.

Problemas comuns