Recomendações de produtos no site

O Web SDK pode exibir recomendações de produtos no seu site: em uma página de produto, no carrinho, em uma página de catálogo ou em uma página 404. Os produtos vêm do Catálogo de produtos do aplicativo. Há duas formas de exibi-los:

Widget: adicione um elemento com o atributo data-pw-recommendations, e o SDK o preenche com uma grade de produtos.
API headless: chame Pushwoosh.recommendations.fetch e renderize os produtos com a sua própria marcação.

Um exemplo ao vivo é a loja de demonstração da Pushwoosh em pushon.pushwoosh.com. Ela tem um bloco de widget na página 404 e blocos headless na página de produto e no carrinho.

Pré-requisitos

Web SDK 3.96.0 ou posterior, carregado a partir da CDN da Pushwoosh conforme descrito no guia do SDK de Web Push 3.0. O pacote npm web-push-notifications ainda não inclui as recomendações.
Produtos no Catálogo de produtos do aplicativo.
Recomendações no site ativadas para o aplicativo. Consulte Ativar as recomendações no site.

Ativar as recomendações no site

Cada aplicativo é ativado separadamente, porque o feed que fornece os blocos é público e não exige um API token. Até lá, o feed responde com um erro e os blocos ficam vazios.

Para ativar as recomendações no site no Painel de Controle:

Vá para Conteúdo → Catálogo de Produtos do aplicativo.
Clique em On-site recommendations.
Ative Show recommendations on my website.
Em Website domains, insira os domínios dos sites que exibirão os blocos, um por linha. Por exemplo, shop.example.com.
Clique em Salvar.

Painel On-site recommendations com a chave Show recommendations on my website ativada, um domínio em Website domains e o botão Save

Depois de salvar:

Website domains exibe os domínios como a Pushwoosh os armazenou: com https:// adicionado, em letras minúsculas e sem duplicatas. Verifique se a lista tem erros de digitação.
Os blocos são carregados apenas nos sites listados. Se você deixar Website domains vazio, os blocos são carregados em qualquer site.
A alteração entra em vigor em até um minuto.

Se você não tiver acesso ao Painel de Controle, peça ao suporte da Pushwoosh ou ao seu Customer Success Manager para ativar as recomendações no site para o aplicativo. Inclua o código do aplicativo e os domínios dos seus sites.

Estratégias de recomendação

Estratégia	O que exibe	Requer
`viewed`	Produtos que este visitante visualizou recentemente. Para um visitante conectado, os produtos visualizados com o user ID dele aparecem primeiro.	Visualizações de produtos enviadas com `trackProductView`.
`bestsellers_30d`	Os produtos mais vendidos do aplicativo nos últimos 30 dias. Produtos esgotados são ignorados.	Eventos de pedido com os itens do pedido.
`also_bought`	Produtos que costumam ser comprados ou visualizados junto com um determinado produto. Produtos esgotados são ignorados.	Visualizações de produtos enviadas com `trackProductView`, eventos de pedido ou quaisquer outros eventos que contenham um ID de produto. Consulte Rastreie a atividade do produto. A solicitação precisa de um ID de produto.

Quando uma estratégia não tem nada para exibir, o feed fornece a estratégia de fallback no lugar dela. A estratégia de fallback é bestsellers_30d por padrão. Defina-a como none para receber uma resposta vazia. A resposta sempre informa qual estratégia foi de fato fornecida, para que você possa alterar o título do bloco.

Rastrear visualizações de produtos

As estratégias viewed e also_bought usam visualizações de produtos. Em cada página de produto, chame trackProductView depois que o SDK estiver pronto:

Pushwoosh.push(() => {
  Pushwoosh.trackProductView({
    id: 'SKU-123',
    name: 'Linen shirt',
    price: 49.9,
    currency: 'USD',
    category: 'Shirts',
    url: 'https://shop.example.com/linen-shirt',
    imageUrl: 'https://shop.example.com/img/linen-shirt.jpg',
  });
});

Apenas id é obrigatório. Use o mesmo ID de produto do seu Catálogo de produtos. O SDK envia um evento PW_ProductView e ignora visualizações repetidas do mesmo produto em até 30 segundos, de modo que recarregar a página não conta como uma segunda visualização.

Enviar eventos de pedido

A estratégia bestsellers_30d conta apenas vendas de eventos de pedido, e é a estratégia de fallback padrão de todos os blocos. Quando um visitante fizer um pedido, envie PW_OrderCreated:

Pushwoosh.push((api) => {
  api.postEvent('PW_OrderCreated', {
    orderId: 'ORDER-10293',
    items: [
      { productId: 'SKU-123', quantity: 1 },
      { productId: 'SKU-456', quantity: 2 },
    ],
  });
});

orderId é obrigatório, porque um pedido sem ele não é contado. Em items, use os mesmos IDs de produto do seu Catálogo de produtos. Quando um pedido mudar, envie PW_OrderUpdated com os mesmos orderId e items. Para enviar os eventos de pedido a partir do seu servidor, consulte Mais vendidos: adicione itens aos seus eventos de pedido.

Adicione um elemento com o atributo data-pw-recommendations onde o bloco deve aparecer. O SDK carrega o widget apenas em páginas que têm esse elemento.

<div
  data-pw-recommendations
  data-pw-strategy="also_bought"
  data-pw-product-id="SKU-123"
  data-pw-fallback="bestsellers_30d"
  data-pw-limit="4"
  data-pw-title="Bought together"
  data-pw-fallback-title="Popular right now"
  data-pw-block="pdp-also-bought"
  data-pw-min-height="260"
></div>

Atributo	Descrição
`data-pw-recommendations`	Marca o elemento como um bloco de recomendações. Obrigatório.
`data-pw-strategy`	`viewed`, `bestsellers_30d` ou `also_bought`. O padrão é `bestsellers_30d`.
`data-pw-fallback`	Estratégia a ser fornecida quando a principal não tem nada: `viewed`, `bestsellers_30d`, `also_bought` ou `none`. O padrão é `bestsellers_30d`.
`data-pw-limit`	Número de produtos, de 1 a 12. O padrão é 6.
`data-pw-product-id`	O produto na tela. Obrigatório para `also_bought`.
`data-pw-exclude`	IDs de produtos separados por vírgula que não devem ser exibidos, por exemplo, os produtos que já estão no carrinho. Até 50.
`data-pw-block`	Nome do bloco. Ele é adicionado aos links dos produtos e aos eventos de clique, para que você possa diferenciar os blocos nas análises.
`data-pw-title`	Título do bloco.
`data-pw-fallback-title`	Título a ser exibido quando a estratégia de fallback foi fornecida, por exemplo, “Popular right now” em vez de “You viewed”.
`data-pw-min-height`	Espaço a ser reservado enquanto o bloco carrega, para evitar um deslocamento do layout. Um número é interpretado como pixels. Qualquer comprimento CSS também funciona.

O widget exibe a imagem, o nome e o preço de cada produto, e leva à página do produto. Os links dos produtos contêm utm_medium=onsite. Um clique em um produto envia um evento PW_RecommendationClick com o nome do bloco, a estratégia e a posição do produto.

Quando você altera qualquer atributo data-pw-*, o bloco é carregado novamente. Por exemplo, atualize data-pw-product-id quando o produto na tela mudar sem recarregar a página.

Blocos para páginas típicas

Página	Estratégia	Atributos a definir
Página de produto	`also_bought`	`data-pw-product-id` com o produto na tela, `data-pw-exclude` com o mesmo ID
Carrinho	`also_bought`	`data-pw-product-id` com um produto do carrinho, `data-pw-exclude` com todos os produtos do carrinho
Página de catálogo ou página inicial	`bestsellers_30d`	—
Página 404	`viewed`	`data-pw-fallback="bestsellers_30d"` e `data-pw-fallback-title`, para que visitantes de primeira viagem vejam produtos populares

Estados do bloco

O widget define o atributo data-pw-state no elemento do bloco:

loading: os produtos estão carregando.
ready: os produtos são exibidos.
empty: nem a estratégia nem a estratégia de fallback têm produtos. O bloco fica vazio.
error: os produtos não foram carregados. O bloco fica vazio.

Use o estado para ocultar a sua própria moldura ou título em volta de um bloco vazio:

.recommendations-frame:has([data-pw-state="empty"], [data-pw-state="error"]) {
  display: none;
}

O widget é renderizado dentro de um shadow DOM, então o CSS do seu site não alcança o conteúdo dele. Em vez disso, defina estas propriedades personalizadas no elemento do bloco:

Propriedade	Descrição	Padrão
`--pw-reco-font`	Família da fonte	Herdada da página
`--pw-reco-accent`	Cor do preço	Cor atual do texto
`--pw-reco-radius`	Raio dos cantos das imagens dos produtos	`8px`
`--pw-reco-columns`	Número de colunas da grade. Em telas com até 600px de largura, a grade sempre tem 2 colunas.	Quantas couberem

[data-pw-recommendations] {
  --pw-reco-columns: 4;
  --pw-reco-radius: 0;
  --pw-reco-accent: #337ab7;
}

Para uma estilização mais detalhada, o título, a grade e cada card de produto são expostos como as CSS parts title, grid e card, por exemplo, [data-pw-recommendations]::part(card).

Aplicações de página única

Por padrão, o SDK procura os blocos uma vez, quando está pronto. Se o seu site renderiza blocos mais tarde, por exemplo, na navegação em uma aplicação de página única, defina recommendations.spa como true na chamada init:

Pushwoosh.push(['init', {
  applicationCode: 'XXXXX-XXXXX',
  // other initialization parameters...
  recommendations: {
    spa: true,
  },
}]);

Substitua XXXXX-XXXXX pelo seu código do aplicativo.

A partir daí, o SDK continua observando a página e carrega o widget assim que um bloco aparece.

Para manter o widget desativado mesmo quando uma página tem elementos data-pw-recommendations, defina recommendations.widget como false. A API headless continua funcionando.

Renderizar blocos com a sua própria marcação

Use a API headless quando o layout do widget não se encaixar no seu design. Solicite produtos com Pushwoosh.recommendations.fetch e informe os cliques com Pushwoosh.recommendations.trackClick:

Pushwoosh.push(async () => {
  const request = {
    strategy: 'also_bought',
    productId: 'SKU-123',
    exclude: ['SKU-123'],
    fallback: 'bestsellers_30d',
    limit: 4,
    block: 'pdp-also-bought',
  };
  const { items, strategy } = await Pushwoosh.recommendations.fetch(request);

  const title = strategy === request.strategy ? 'Bought together' : 'Popular right now';
  renderBlock(title, items, (item, index) => {
    Pushwoosh.recommendations.trackClick({
      block: request.block,
      strategy,
      productId: item.id,
      position: index + 1,
    });
  });
});

fetch aceita os mesmos parâmetros que os atributos do widget: strategy, fallback, limit, productId, exclude e block. Ela retorna:

items: os produtos. Cada um tem id, title, description, image_url, url, price, price_formatted, old_price_formatted (apenas para um produto em promoção), currency, category e sku.
strategy: a estratégia de fato fornecida. Ela difere da solicitada quando a estratégia de fallback foi fornecida, e é none quando a resposta está vazia.

Se a solicitação falhar, fetch lança um erro. Capture-o e oculte o bloco.

trackClick envia o evento PW_RecommendationClick. Ele é entregue mesmo quando o clique abre outra página. position é o lugar do produto no bloco, a partir de 1.

Comportamento sem consentimento para comunicação

Se a comunicação com a Pushwoosh estiver desativada para o visitante, por exemplo, com communicationEnabled: false na chamada init (consulte Gerenciar o consentimento do usuário para notificações push na Web):

trackProductView e trackClick não enviam nada.
Os blocos continuam exibindo produtos, mas a solicitação não identifica o visitante. A estratégia viewed não tem histórico para usar, então a estratégia de fallback é fornecida.

Assim que o visitante ativa a comunicação, as visualizações de produtos e os cliques voltam a ser rastreados.