Smart Offers: documentação completa

O Smart Offers é um módulo compatível com o PrestaShop 8 e 9 que permite criar ofertas agrupadas 1+1, packs em grosso, packs de vários produtos e ofertas à escolha, com adição automática dos produtos oferecidos ao carrinho e uma apresentação cuidada na ficha de produto.

Panorâmica

O Smart Offers cobre num só módulo os quatro formatos de oferta agrupada mais usados no comércio eletrónico, sem configuração complexa. O motor avalia o carrinho a cada alteração, acrescenta automaticamente os produtos oferecidos assim que as condições estão reunidas, e cria uma regra de carrinho que torna essas unidades gratuitas. A experiência do cliente é imediata e legível.

Compatibilidade com o PrestaShop 8 e 9

Desde a versão 2.0.0, um único ficheiro ZIP cobre o PrestaShop 8.0 a 9.x. Não há um ramo separado a escolher na transferência: o módulo deteta a versão da loja em execução e adapta as chamadas às APIs que mudaram entre as duas gerações.

Instalação

1. Descarregue o ficheiro dfoffers-vX.Y.Z.zip a partir da sua área de cliente DataFirefly
2. No back-office do PrestaShop, vá a Módulos → Gestor de módulos
3. Clique no botão Carregar um módulo, no topo da página
4. Arraste o ficheiro ZIP ou clique para o selecionar
5. A instalação é automática: as tabelas são criadas, os hooks registados, e aparece um novo separador Catálogo → Ofertas agrupadas no menu

Os quatro tipos de oferta

1+1 no mesmo produto

O formato clássico do leve dois, pague um: o cliente compra uma unidade de um produto e recebe gratuitamente outra unidade do mesmo produto. Configura:

• Um só produto (que serve ao mesmo tempo de acionador e de recompensa)
• A quantidade a comprar para acionar a oferta (geralmente 1)
• A quantidade oferecida (geralmente 1)

Exemplo típico: «Na compra de 1 par de meias, o segundo é oferecido.» Quando o cliente acrescenta o par ao carrinho, o motor acrescenta um segundo e aplica um desconto igual ao preço unitário.

Compre X, receba Y oferecidos (produtos diferentes)

Formato de bundle: vários produtos acionadores distintos têm de estar no carrinho para a oferta se ativar, e são então oferecidos um ou vários produtos diferentes. Configura:

• A lista dos produtos acionadores, com a respetiva quantidade
• A lista dos produtos oferecidos, com a respetiva quantidade

Exemplo típico: «Na compra conjunta de um creme de dia e de um sérum, receba uma amostra de máscara oferecida.» O motor verifica que todos os acionadores estão presentes antes de ativar a oferta.

Escolha entre combinações

Formato de composição livre: define um conjunto de produtos ou combinações candidatas, entre os quais o cliente compõe o seu lote. O motor identifica automaticamente as unidades mais baratas do carrinho como sendo as oferecidas, o que corresponde à interpretação comercial habitual do leve N, pague M.

• A lista dos produtos ou combinações candidatos
• O número de unidades a comprar nesse conjunto
• O número de unidades oferecidas (as mais baratas)

Exemplo típico: «3 t-shirts compradas da nossa seleção, a mais barata é oferecida.» O cliente compõe o lote, o motor não mexe no carrinho e aplica o desconto às unidades mais baratas.

Pack em grosso

Formato B2B e de escoamento de stock: por cada lote de X unidades compradas de um produto, o cliente recebe Y unidades gratuitas de outro produto. Configura:

• O produto acionador, com a quantidade do patamar (por exemplo, 10)
• O produto oferecido, com a quantidade oferecida (por exemplo, 20)

Exemplo típico: «Na compra de 10 garrafas de vinho, 2 copos oferecidos.» É prático para fornecedores que queiram empurrar um produto complementar ou escoar stock parado, associando-o a um produto que vende bem.

Criar a sua primeira oferta

No back-office, vá a Catálogo → Ofertas agrupadas e clique em Nova oferta.

Passo 1: escolher o tipo

Quatro cartões visuais apresentam os tipos disponíveis, com uma descrição curta. Clique no que corresponde à sua operação comercial. O formulário adapta-se automaticamente e mostra apenas os campos pertinentes para esse tipo.

Passo 2: dar nome e etiqueta à oferta

Preencha:

• Nome da oferta (obrigatório): é o que o cliente vê na faixa. Há um campo por cada idioma ativo da loja.
• Texto da etiqueta (opcional, até 64 caracteres): mensagem curta que aparece na pastilha, no topo da faixa (por exemplo, 1+1 OFERTA, OFERTA ESPECIAL ou BLACK FRIDAY).
• Cor da etiqueta: seis predefinições DataFirefly e um seletor de cor livre. A cor serve para a faixa da ficha de produto e também para a pastilha de presente no carrinho.

Passo 3: acrescentar os produtos acionadores

Clique em Acrescentar um produto acionador. Abre-se uma janela de pesquisa com um campo que consulta o seu catálogo em direto (com um atraso de 250 ms após a última tecla). Escreva um nome, uma referência ou um EAN, e os resultados aparecem de imediato.

Clique no produto para o acrescentar. Se o produto tiver combinações, as variantes aparecem como botões por baixo do resultado; clique na que lhe interessa para a acrescentar diretamente. Indique a quantidade necessária no campo que aparece à direita da linha.

Passo 4: acrescentar os produtos oferecidos

O procedimento é o mesmo para os produtos oferecidos. Esta secção fica oculta no tipo Escolha entre combinações, uma vez que as combinações servem ao mesmo tempo de candidatas e de recompensas.

Passo 5: regras específicas

• Acumulável: se estiver ativo, a oferta aplica-se várias vezes, uma por cada lote acionador. Sem acumulação, a oferta aplica-se uma só vez, qualquer que seja o número de unidades. Vem inativo por predefinição, para proteger as suas margens.
• No tipo Escolha entre combinações, aparecem dois campos adicionais: quantas unidades o cliente tem de comprar e quantas são oferecidas.

Passo 6: ativação

• Datas de validade: deixe vazias para uma oferta permanente. Preencha a data de início ou de fim para automatizar a ativação. Uma data ilegível é recusada, e a data de fim tem de ser posterior à de início.
• Prioridade: se várias ofertas puderem aplicar-se ao mesmo tempo, a de prioridade mais baixa é avaliada primeiro.
• Estado: interruptor de ligado e desligado, ativo por predefinição. É prático para suspender uma oferta sem a eliminar.

Passo 7: lojas (em multiloja)

Assinale as lojas onde a oferta deve estar disponível. Não assinalar nada equivale a ativar a oferta em todas as lojas.

Alterar ou eliminar uma oferta

Em Catálogo → Ofertas agrupadas, cada linha da lista tem um botão Modificar e, no menu pendente, Eliminar. O interruptor da coluna Ativa permite também suspender uma oferta sem a eliminar. Para atuar sobre várias ofertas ao mesmo tempo, assinale-as e use as ações em massa, no fundo da lista.

Como funciona o motor de adição automática

O motor liga-se ao hook actionCartSave do PrestaShop e corre a cada alteração do carrinho (adição, remoção, mudança de quantidade, fusão no início de sessão).

1. Obtém todas as ofertas ativas para a loja atual
2. Em cada oferta, calcula a quantidade paga de cada produto acionador (quantidade total no carrinho menos o que o motor já tinha acrescentado numa avaliação anterior)
3. Avalia se as condições da oferta estão reunidas
4. Em caso afirmativo, acrescenta ao carrinho os produtos oferecidos em falta, através de Cart::updateQty
5. Cria ou atualiza uma regra de carrinho (CartRule), com um desconto fixo com IVA igual ao valor das unidades oferecidas
6. Regista na tabela ps_dfoffers_cart_auto as unidades que acrescentou, para as distinguir das que o cliente acrescentou por si

Revogação limpa

Se o cliente retirar um produto acionador ou reduzir a quantidade abaixo do limiar, o motor reavalia a oferta no actionCartSave seguinte. Se a condição já não estiver reunida, retira as unidades que tinha acrescentado (sem tocar nas que o cliente acrescentou, graças ao seguimento) e elimina a regra de carrinho associada.

Definições do módulo

Em Módulos → Gestor de módulos → Smart Offers → Configurar, há duas definições globais:

• Posição da faixa na ficha de produto. Cinco posições, cada uma correspondente a um hook do tema Classic:
  • Sob o bloco Adicionar ao carrinho (predefinição): displayProductAdditionalInfo
  • Sob o preço: displayProductPriceBlock, tipo after_price
  • Sob as imagens do produto: displayAfterProductThumbs
  • No bloco de confiança, sob os ícones de pagamento: displayReassurance
  • Largura total, sob a ficha: displayFooterProduct

  O módulo está registado nos cinco hooks e só o escolhido apresenta a faixa. Se o seu tema não chamar o hook selecionado, a faixa não aparece: escolha outro.

• Faixa compacta. Força em todo o lado a disposição densa (margens reduzidas, miniaturas de 92 px, grupos lado a lado). Sem esta opção, a faixa já adota essa disposição por si quando a sua coluna tem menos de 520 px, e empilha os grupos abaixo de 300 px. A deteção baseia-se na largura da coluna, e não na da janela: uma ficha de produto estreita num site largo é tratada como um telemóvel.

Apresentação na ficha de produto

Em cada ficha de produto acionador, é apresentada uma faixa em gradiente na posição escolhida nas definições (por predefinição sob o botão Adicionar ao carrinho). Contém:

• Uma pastilha branca com ícone de presente, com o texto da etiqueta
• O título da oferta
• Uma mensagem dinâmica que depende do tipo de oferta («Compre 1, receba mais 1 gratuitamente», «Por cada lote de 10, receba mais 20 gratuitamente», entre outras)
• Uma grelha com as miniaturas clicáveis dos produtos abrangidos, separados em dois grupos, Compre e Receba oferecido, com um separador SVG circular entre eles

A cor da faixa retoma a da etiqueta configurada na oferta. A apresentação é responsiva: em telemóvel, os dois grupos empilham-se na vertical e o separador roda para apontar para baixo.

Apresentação no carrinho

Há dois indicadores distintos que ajudam o cliente a identificar os produtos oferecidos no carrinho.

Pastilha de presente em cada linha

Em cada linha do carrinho com unidades acrescentadas automaticamente por uma oferta, aparece uma pequena pastilha colorida 🎁 ×N oferecido na coluna de informação do produto, por baixo do preço e das combinações. A cor retoma a da etiqueta da oferta, e a pastilha indica quantas unidades dessa linha são gratuitas (útil quando parte da quantidade é paga e outra parte oferecida, por exemplo num 1+1 do mesmo produto).

Rodapé detalhado do carrinho

No fundo da grelha de produtos, um bloco verde resume as ofertas ativadas no carrinho. Em cada oferta, o bloco mostra:

• O nome da oferta e o texto da etiqueta (numa pastilha colorida)
• A lista dos produtos oferecidos por essa oferta, em cartões visuais com miniatura redonda, nome (com a combinação, por exemplo «Almofada urso castanho (Cor: Branco)») e quantidade
• Cada cartão é clicável e remete para a ficha do produto oferecido

O cliente pode assim verificar num relance o que obteve gratuitamente e graças a que operação comercial.

Casos particulares e comportamentos

Porque é que o 1+1 no mesmo produto tem tratamento próprio

Quando o produto acionador é também o produto de recompensa, muitos módulos de ofertas agrupadas do mercado cometem o erro de identificar a unidade paga pelo cliente como sendo já a unidade oferecida, e aplicam-lhe o desconto. No fim, o cliente paga zero por uma unidade em vez de pagar uma e receber uma segunda gratuitamente.

O Smart Offers trata este caso com uma lógica precisa: a quantidade alvo no carrinho é a quantidade paga pelo cliente mais a quantidade de recompensa. Quando o cliente acrescenta uma unidade, o motor acrescenta uma segunda para que o carrinho tenha duas, e o desconto aplica-se apenas à segunda. O cliente paga assim o preço de uma unidade para ter duas no carrinho.

Ofertas em produtos com combinações

Uma oferta pode visar uma combinação concreta ou o produto no seu conjunto. No back-office, acrescentar o produto por Produto principal (sem combinação) guarda um curinga: o motor lê esse curinga exatamente como a faixa, ou seja, «qualquer combinação».

• Acionador com curinga: a quantidade comprada é a soma de todas as combinações do produto presentes no carrinho. Duas almofadas brancas e uma preta contam como três unidades.
• Recompensa com curinga: o motor tem de escolher uma combinação concreta antes de acrescentar ao carrinho. Prefere a que o cliente já tem no carrinho para esse produto (um 1+1 numa almofada branca acrescenta uma almofada branca). Se o produto ainda não estiver no carrinho, usa a combinação predefinida do catálogo. Um produto sem combinações é acrescentado tal como está.
• Escolha entre combinações com curinga: cada combinação presente no carrinho passa a ser uma linha candidata própria, o que permite à ordenação por preço designar as mais baratas.

Acumulação dos lotes (opção acumulável)

Sem acumulação, a oferta aplica-se uma só vez, qualquer que seja o número de lotes acionadores presentes no carrinho. Se o cliente comprar 5 unidades de um produto com uma oferta 1+1 e a acumulação desativada, recebe 1 unidade oferecida, e não 5.

Com a acumulação ativa, o motor multiplica o número de lotes de recompensa pelo número inteiro de lotes acionadores presentes. Na mesma oferta 1+1, com acumulação ativa e 5 unidades no carrinho, o cliente recebe 5 unidades oferecidas (carrinho final de 10 unidades, 5 pagas).

Stock e indisponibilidade

A adição dos produtos oferecidos ao carrinho passa por Cart::updateQty, que respeita as regras de stock nativas do PrestaShop. Se um produto oferecido estiver esgotado e a loja não permitir encomendas sem stock, a adição falha em silêncio e o desconto não é aplicado. A condição fica pronta a acionar-se assim que houver reposição.

Várias ofertas em simultâneo no mesmo carrinho

Cada oferta gera a sua regra de carrinho, com partial_use ativo. Isso permite empilhar várias ofertas concorrentes no mesmo carrinho sem conflito, e mantém a compatibilidade com os códigos promocionais normais que os seus clientes possam introduzir.

Idiomas do módulo

Desde a 2.1.2, o idioma de origem do módulo é o inglês e são fornecidas sete traduções na pasta translations/: francês, alemão, italiano, espanhol, neerlandês, português e polaco. Cobrem a faixa da ficha de produto, o carrinho, o nome da regra de carrinho visto pelo cliente, o formulário de criação de oferta e as mensagens do seletor de produtos.

Cada cadeia continua alterável em Internacional → Traduções, escolhendo o módulo dfoffers. Uma loja num idioma não fornecido mostra o inglês e pode ser traduzida no mesmo sítio.

Arquitetura técnica

Hooks utilizados

• displayProductAdditionalInfo, displayProductPriceBlock (tipo after_price), displayAfterProductThumbs, displayReassurance, displayFooterProduct: faixa na ficha de produto, apenas um ativo consoante as definições
• displayShoppingCartFooter: rodapé detalhado na página do carrinho
• displayProductPriceBlock: pastilha de presente na coluna de informação de cada linha do carrinho (tipo unit_price, apenas na página do carrinho)
• displayCartExtraProductActions: pastilha de presente em recurso, na coluna de ações
• actionCartSave: motor de avaliação e de adição automática
• actionFrontControllerSetMedia e actionAdminControllerSetMedia: injeção dos CSS e JS
• actionObjectProductDeleteAfter: limpeza automática das ofertas que referenciem um produto eliminado

Apenas o actionCartSave e o actionFrontControllerSetMedia são considerados indispensáveis à instalação. Os hooks de apresentação que um tema não implemente são registados no log, sem fazer falhar a instalação.

Tabelas acrescentadas

• ps_dfoffers_offer: configuração de cada oferta (tipo, datas, prioridade, acumulação)
• ps_dfoffers_offer_lang: nome, etiqueta e descrição traduzidos por idioma
• ps_dfoffers_trigger: produtos acionadores de cada oferta
• ps_dfoffers_reward: produtos de recompensa de cada oferta
• ps_dfoffers_shop: associação entre oferta e loja, em multiloja
• ps_dfoffers_cart_auto: seguimento das unidades acrescentadas automaticamente, por carrinho e por oferta, com o identificador da regra de carrinho gerada

Todas as tabelas levam o prefixo configurado na sua instalação do PrestaShop (ps_ por predefinição). O esquema é idêntico no PrestaShop 8 e 9, o que torna a migração transparente.

A classe DfOfferCompat

Todas as diferenças de API entre o PrestaShop 8 e o 9 estão concentradas em classes/DfOfferCompat.php. O resto do módulo nunca testa diretamente a versão do PrestaShop. Os pontos absorvidos por esta classe são:

• Leitura das combinações: o PrestaShop 9 retirou o argumento de idioma de Product::getAttributeCombinations(), onde o primeiro parâmetro passou a ser o indicador booleano de agrupamento.
• URL AJAX do back-office: no PrestaShop 9, o par ajax e action tem de passar pelo quarto argumento de getAdminLink(), porque o token é calculado antes da fusão dos parâmetros.
• Resposta JSON: o método de envio tem propositadamente um nome diferente de ajaxRender(), cuja assinatura da classe-mãe não deve ser substituída.
• Separador de administração: o PrestaShop 9 introduziu colunas de tradução adicionais, preenchidas sob condição para não criar uma propriedade dinâmica no PrestaShop 8.

Substituir os templates no seu tema

O CSS do módulo está isolado sob o prefixo .dfoffers-, para evitar conflitos com a sua folha de estilos. Se quiser alterar a apresentação, copie os templates de /modules/dfoffers/views/templates/hook/ para /themes/o-seu-tema/modules/dfoffers/views/templates/hook/ e personalize-os. Há três templates disponíveis:

• product-banner.tpl: faixa na ficha de produto
• cart-offer.tpl: bloco de resumo no rodapé do carrinho
• cart-line-gift.tpl: pastilha de presente nas linhas do carrinho

Atualização do módulo

Para atualizar para uma nova versão, basta carregar o novo ZIP a partir do Gestor de módulos. O PrestaShop deteta a mudança de versão no config.xml e executa automaticamente os scripts de atualização presentes em /upgrade/upgrade-X.Y.Z.php, que tratam, por exemplo, de registar novos hooks acrescentados entre versões.

Migrar uma loja do PrestaShop 8 para o PrestaShop 9

Como o esquema da base de dados é idêntico, as suas ofertas, traduções e associações de lojas passam a migração sem transformação. O procedimento recomendado é:

1. Passe o módulo para a 2.x antes de migrar a loja, enquanto ela ainda corre em PrestaShop 8. As versões 2.x funcionam nas duas gerações, pelo que reduz o número de variáveis se algo correr mal.
2. Migre a loja para o PrestaShop 9, segundo o procedimento oficial do PrestaShop.
3. Vá a Design → Posições e confirme que os hooks do módulo continuam ligados. Uma migração pode perder alguns.
4. Se faltarem hooks, volte a carregar o ZIP: o script de atualização volta a registar cada hook em falta e limpa as linhas de seguimento cujo carrinho já não existe.

Resolução de problemas

Os produtos oferecidos não são acrescentados ao carrinho

1. Limpe a cache do PrestaShop em Parâmetros avançados → Desempenho
2. Confirme que o hook actionCartSave tem mesmo o módulo, em Design → Posições
3. Confirme que o produto oferecido está disponível (sem rutura, se as encomendas sem stock estiverem proibidas; não desativado; associado à loja atual)
4. Se o produto acionador tiver combinações e a faixa aparecer corretamente na ficha, confirme que o módulo está na 2.0.1 ou superior: as versões anteriores não liam o curinga «todas as combinações» do lado do motor
5. Consulte Parâmetros avançados → Registos, à procura de dfoffers: o motor deixa registo da sua execução em cada adição ao carrinho

O desconto não é aplicado apesar de o produto ser acrescentado

Procure nos registos a linha checkValidity que se segue à criação da regra de carrinho. O PrestaShop indica aí exatamente porque é que uma regra foi recusada (rutura de stock, restrição de cliente, moeda diferente, entre outras).

A pastilha de presente não aparece nas linhas do carrinho

O módulo procura primeiro o hook displayProductPriceBlock em cart-detailed-product-line.tpl, e depois o displayCartExtraProductActions. Os temas Classic do PrestaShop 8 e 9, tal como a maioria dos temas comerciais, contêm pelo menos um dos dois. Se o seu tema personalizado não implementar nenhum, acrescente uma destas linhas ao seu ficheiro cart-detailed-product-line.tpl, de preferência a primeira, na coluna de informação do produto:

{hook h='displayProductPriceBlock' product=$product type="unit_price"}
{hook h='displayCartExtraProductActions' product=$product}

A pastilha aparece cortada ou só mostra o ícone

É o sintoma das versões 2.1.0 e 2.1.1 no tema Classic, em que a pastilha era apresentada na coluna de ações, demasiado estreita para texto. Foi corrigido na 2.1.2, com a passagem para a coluna de informação do produto. Atualize o módulo.

Erro 500 ao guardar uma oferta

Antes da 2.2.0, um nome ou texto de etiqueta com =, ;, #, { ou } era recusado pelos validadores do PrestaShop e a gravação terminava numa página em branco. Desde a 2.2.0 esses caracteres são aceites, e qualquer valor realmente inválido é assinalado no formulário em vez de provocar um erro. Se ainda encontrar um 500, consulte Parâmetros avançados → Registos: a causa fica registada sob dfoffers save failed.

A pesquisa de produtos do back-office não devolve nada depois de uma migração para o PrestaShop 9

Limpe a cache do PrestaShop e recarregue a página de criação de oferta. O URL do endpoint de pesquisa é construído do lado do servidor na apresentação do formulário; uma página em cache anterior à migração pode ainda levar um URL antigo. Se o problema persistir, abra a consola do navegador: uma resposta 404 no pedido de pesquisa indica que o separador do módulo não foi corretamente recriado, e uma reinstalação do módulo corrige isso sem perder as ofertas.

A instalação parece correr bem mas não é possível criar ofertas

Antes da 2.0.0, uma falha na criação de tabelas durante a instalação era silenciosa e o módulo aparecia como instalado. Desde a 2.0.0, essa situação faz falhar a instalação com uma mensagem explícita. Se encontrar este caso numa versão antiga, verifique as permissões do utilizador de MySQL para a criação de tabelas, e desinstale e reinstale depois o módulo.

Perguntas frequentes

O módulo é compatível com o PrestaShop 9?

Sim, desde a versão 2.0.0. O mesmo ficheiro ZIP instala-se no PrestaShop 8.0 tal como no PrestaShop 9.x. As diferenças de API são absorvidas pela classe interna DfOfferCompat, pelo que não há um ramo separado a escolher na transferência. As versões 1.x ficavam limitadas ao PrestaShop 8.0 a 8.99.

Qual é o impacto no desempenho?

O motor executa uma consulta SQL por oferta ativa na loja e avalia depois as condições em memória. Num catálogo com uma dezena de ofertas ativas, a avaliação completa demora em média menos de cinquenta milissegundos. O valor é igual no PrestaShop 8 e 9.

Posso usar o módulo com um tema headless?

O motor de adição automática é independente do tema e funciona em qualquer front-office que passe por Cart::updateQty ou pela API REST do PrestaShop. A faixa da ficha de produto e a pastilha de presente do carrinho são hooks nativos do Smarty e precisam de um tema clássico para aparecer. Num front-office headless, pode expor os dados por uma API à medida que consulte diretamente as tabelas ps_dfoffers_offer e ps_dfoffers_cart_auto.

O módulo trata várias moedas?

Sim. A regra de carrinho gerada em cada oferta usa a moeda do carrinho em curso. Se o cliente mudar de moeda, a regra é regenerada com o valor correto no actionCartSave seguinte.

O que acontece se clicar em Repor no gestor de módulos?

O módulo é desinstalado e reinstalado no mesmo pedido, o que elimina e recria as tabelas: todas as suas ofertas são perdidas. Desde a 2.0.0, esta operação recria corretamente as tabelas, ao passo que as versões anteriores deixavam a loja sem tabelas nenhumas. Nos dois casos, faça uma cópia de segurança antes de repor.