Smart Bundle Engine: documentação

Apresentação

O Smart Bundle Engine analisa o histórico das suas encomendas WooCommerce para detetar os produtos realmente comprados em conjunto, gera automaticamente os conjuntos correspondentes e apresenta-os na ficha de produto, no carrinho e no e-mail pós-compra, com um controlo de margem que limita automaticamente o desconto se for necessário.

Instalação

1. Descarregue o ficheiro df-smart-bundle.zip a partir da sua conta de cliente DataFirefly.
2. Na administração do WordPress, vá a Plugins → Adicionar → Carregar plugin.
3. Selecione o ZIP, clique em Instalar agora e ative a extensão.
4. Aparece um novo menu Smart Bundles na barra lateral da administração.

Na ativação, o plugin cria 4 tabelas dedicadas (df_sbe_cooccurrence, df_sbe_bundles, df_sbe_bundle_items, df_sbe_analysis_state) e agenda o cron de análise.

Arranque rápido

1. Vá a Smart Bundles → Análise e clique em Lançar a análise agora.
2. Concluída a análise, a tabela Top de afinidades de compra mostra os pares detetados com as respetivas métricas (ocorrências, confiança, lift).
3. Se a geração automática estiver ativa (por predefinição), os conjuntos são criados automaticamente: consulte-os em Smart Bundles → Conjuntos.
4. Visite uma ficha de produto abrangida do lado da loja: o bloco «Comprado frequentemente com» aparece por baixo do resumo do produto.

Análise de coocorrência

O motor percorre as encomendas concluídas e em processamento na janela de análise configurada (180 dias por predefinição), em lotes de 200 encomendas. Em cada encomenda com vários produtos, todos os pares são extraídos e contabilizados.

As três métricas

• Ocorrências: número de encomendas que contêm o par A+B.
• Confiança: P(B|A) em percentagem: em que percentagem das encomendas que contêm A se encontra B. Uma confiança de 20 significa que B aparece em 20% das encomendas que contêm A.
• Lift: razão entre a frequência observada do par e a frequência esperada se A e B fossem independentes. Um lift superior a 1 indica uma afinidade real; superior a 2, uma afinidade forte.

Agendamento

A análise corre automaticamente através do WP-Cron (hook df_sbe_run_analysis). Cada execução trata até 25 lotes de 200 encomendas e retoma no disparo seguinte graças a um cursor persistente: nenhuma encomenda é tratada duas vezes. O botão Reinicializar o estado esvazia as tabelas de análise e recomeça do zero.

Geração automática dos conjuntos

Depois de cada análise completa, o motor seleciona os pares que ultrapassam os seus limiares e cria os conjuntos correspondentes. Três definições controlam a seleção:

• Coocorrências mínimas (3 por predefinição): número mínimo de encomendas que contêm o par.
• Confiança mínima (10% por predefinição): limiar de confiança abaixo do qual o par é ignorado.
• Máximo de conjuntos por produto (3 por predefinição): evita a saturação de um mesmo produto.

Os pares retidos são ordenados por pontuação (lift × ocorrências). Os conjuntos criados automaticamente recebem a origem «Auto»; os conjuntos já existentes com os mesmos produtos nunca são duplicados. Os conjuntos manuais são sempre conservados nas novas análises.

Gestão dos conjuntos

O ecrã Smart Bundles → Conjuntos lista todos os conjuntos com os produtos, o desconto, a margem mínima, os contextos de apresentação, as visualizações e as conversões. Pode filtrar por estado, origem (auto ou manual) ou pesquisa livre.

Criar ou alterar um conjunto

1. Clique em Novo conjunto ou em Editar num conjunto existente.
2. Pesquise e acrescente os produtos (no mínimo 2): a quantidade de cada artigo é ajustável e a ordem reorganiza-se por arrastar e largar.
3. Defina o desconto (percentagem ou montante fixo) e a margem mínima.
4. Assinale os contextos de apresentação pretendidos: ficha de produto, carrinho, e-mail.
5. A prioridade determina a ordem de apresentação quando vários conjuntos são elegíveis (mais alta = primeiro).

Num conjunto existente, uma tabela Pré-visualização da tarifação mostra em direto o subtotal, o custo estimado, o desconto pedido face ao aplicado, o preço final e a margem real.

Controlo de margem

Cada conjunto tem um limiar de margem mínima (em % do preço final). O motor calcula o preço mínimo correspondente:

preco_min_final = custo_total / (1 − margem_min / 100)

Se o desconto pedido fizesse o preço final descer abaixo desse mínimo, é limitado automaticamente ao desconto máximo compatível. O desconto apresentado na loja é portanto sempre seguro.

Origem do custo

O custo de cada produto é determinado por esta ordem:

1. Meta de produto: a chave _df_cost_price por predefinição, configurável nas definições (compatível com o Cost of Goods e com os outros plugins de custo de compra).
2. Rácio de recurso: nos produtos sem custo preenchido, assume-se uma percentagem do preço de venda (50% por predefinição).

Apresentação na loja

Ficha de produto

O bloco insere-se no hook woocommerce_after_single_product_summary com uma prioridade configurável (15 por predefinição, logo antes dos produtos relacionados). Mostra as miniaturas dos produtos ligadas por «+», o subtotal riscado, o preço do conjunto e o botão de adição num clique.

Carrinho

As sugestões aparecem por baixo da tabela do carrinho (woocommerce_after_cart_table). Os conjuntos cujos produtos já estão todos no carrinho são ocultados automaticamente.

E-mail pós-compra

É inserido um bloco de sugestão nos e-mails Encomenda concluída e Encomenda em processamento (apenas para clientes), em variantes HTML e texto simples, com uma ligação direta de regresso à loja.

Cada contexto pode ser ativado de forma independente e o seu título é personalizável nas definições.

Aplicação do desconto

O plugin nunca altera os preços dos produtos. Quando um conjunto é acrescentado ao carrinho, cada artigo leva um marcador interno; assim que todos os artigos do conjunto estão presentes, o desconto é aplicado como uma taxa negativa do WooCommerce («Desconto de conjunto»). Esta abordagem:

• preserva os preços de linha e os relatórios de vendas;
• mantém-se compatível com os impostos, os portes e os códigos promocionais;
• retira automaticamente o desconto se um artigo do conjunto for removido do carrinho.

Acompanhamento do desempenho

Cada apresentação de um conjunto incrementa o seu contador de visualizações; cada encomenda que contenha um conjunto completo incrementa as suas conversões (na passagem ao estado «em processamento» ou «concluída», com uma proteção contra a contagem dupla). A taxa de conversão por conjunto aparece na lista de conjuntos, e o ecrã Análise apresenta as estatísticas globais: encomendas analisadas, pares detetados, conjuntos ativos, visualizações e conversões acumuladas.

Referência das definições

Análise de coocorrência

• Janela de análise (dias): 180 por predefinição. Encomendas concluídas e em processamento nesse período.
• Coocorrências mínimas: 3 por predefinição.
• Confiança mínima (%): 10 por predefinição.
• Geração automática de conjuntos: ativa por predefinição.
• Máximo de conjuntos por produto: 3 por predefinição.

Tarifação e margem

• Desconto predefinido (%): 10, aplicado aos conjuntos gerados automaticamente.
• Margem mínima predefinida (%): 20.
• Chave meta do custo de compra: _df_cost_price.
• Rácio de custo de recurso (%): 50.

Apresentação

• Contextos: ficha de produto / carrinho / e-mail, ativáveis em separado.
• Prioridade do hook da ficha de produto: 15 por predefinição.
• Títulos: um título personalizável por contexto.

Multilingue

O plugin é fornecido com 5 idiomas (FR, EN, ES, DE, IT) em formato .po/.mo, mais um ficheiro .pot para as suas próprias traduções (textdomain df-smart-bundle). Compatível com Polylang e WPML: o idioma apresentado segue a locale do site ou do utilizador.

Desinstalação

A desativação do plugin retira simplesmente o cron agendado e os seus dados são conservados. A remoção do plugin (através de Plugins → Eliminar) executa o uninstall.php, que elimina definitivamente as 4 tabelas, todas as opções e os metadados de encomenda criados pelo plugin (compatível com HPOS).

Resolução de problemas

Não é gerado nenhum conjunto

• Verifique que a análise correu mesmo: Smart Bundles → Análise tem de mostrar um número de encomendas analisadas superior a zero.
• Baixe os limiares (coocorrências mínimas, confiança mínima) se o seu histórico for reduzido.
• Verifique que a geração automática está ativa nas definições.

O conjunto não aparece na loja

• O conjunto tem de estar ativo e o contexto em causa assinalado.
• Um conjunto cujo desconto calculado seja nulo (limitação de margem total) é ocultado na ficha de produto.
• No carrinho, um conjunto já completo é ocultado por conceção.
• Limpe a cache de página se usar um plugin de cache.

O desconto aplicado é inferior ao desconto configurado

É a limitação de margem a atuar: o custo total do conjunto não permite o desconto pedido sem descer abaixo da margem mínima. Verifique os custos dos produtos ou ajuste o limiar de margem do conjunto.

FAQ

O plugin funciona com produtos variáveis?

A análise e os conjuntos operam ao nível do produto principal. As variações de um mesmo produto são contabilizadas em conjunto.

Posso excluir determinados produtos da análise?

Não na versão 1.0.0: elimine ou desative simplesmente os conjuntos indesejados; não são recriados se os eliminar depois de desativar a geração automática.

Os conjuntos são compatíveis com os códigos promocionais?

Sim. O desconto de conjunto é uma taxa negativa independente dos cupões do WooCommerce; os dois acumulam-se.

Qual é o impacto no desempenho?

A análise corre em segundo plano por lotes. Do lado da loja, as consultas de conjuntos são leves (tabelas indexadas) e os recursos só são carregados nas páginas de produto e de carrinho.