# 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…

- Página: <https://www.datafirefly.com/pt/documentation/dfsmartbundle/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfsmartbundle/index.md), [en](https://www.datafirefly.com/en/documentation/dfsmartbundle/index.md), [es](https://www.datafirefly.com/es/documentation/dfsmartbundle/index.md), [de](https://www.datafirefly.com/de/documentation/dfsmartbundle/index.md), [it](https://www.datafirefly.com/it/documentation/dfsmartbundle/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsmartbundle/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsmartbundle/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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.

**Requisitos:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+. A compatibilidade HPOS (High-Performance Order Storage) é declarada nativamente.

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.

**Dica:** a análise precisa de pelo menos algumas dezenas de encomendas com vários produtos para produzir afinidades utilizáveis. Se o seu histórico for curto, baixe temporariamente o limiar mínimo de coocorrências para 2 nas definições.

## 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.

**Atenção:** se o WP-Cron estiver desativado no seu servidor (`DISABLE_WP_CRON`), certifique-se de que um cron de sistema chama o `wp-cron.php` com regularidade, caso contrário a análise só corre nas execuções manuais.

## 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).

**Dica:** preencha os custos reais prioritariamente nos seus produtos mais vendidos: a limitação de margem passa a ser exata nos conjuntos que mais contam.

## 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.