Avaliações Verificadas WooCommerce: documentação

O DataFirefly Reviews (dfreviews) transforma o sistema de avaliações nativo do WooCommerce numa máquina de prova social: pedidos de avaliação automáticos após a compra, distintivo de Compra verificada, fotografias dos clientes, votos de utilidade, resumo por IA das avaliações na ficha de produto, resposta automática às avaliações por IA, código promocional de recompensa e rich snippets Schema.org. Esta documentação cobre a instalação, a configuração completa e a resolução de problemas.

Instalação

1. Na administração do WordPress, abra Plugins → Adicionar → Carregar plugin.
2. Selecione o ficheiro dfreviews-1.0.0.zip, clique em Instalar agora e depois em Ativar.
3. Aparece um novo submenu WooCommerce → DF Reviews: é o centro de controlo do plugin.

Requisitos: WooCommerce 8 ou 9, WordPress 6.0+, PHP 8.0 a 8.3. O plugin é compatível com HPOS (High-Performance Order Storage) e funciona sem jQuery nem Composer.

Configuração da chave OpenAI

O resumo por IA e a resposta automática usam a sua própria chave de API da OpenAI:

1. Crie uma chave em platform.openai.com.
2. Cole-a em WooCommerce → DF Reviews → Settings, secção OpenAI.
3. O modelo predefinido é o gpt-4o-mini, o mais económico e recomendado. Um resumo ou uma resposta custa tipicamente bem menos de um cêntimo.

Pedidos de avaliação automáticos

Secção Review requests das definições:

• Estado de disparo: o pedido é colocado em fila quando uma encomenda atinge esse estado (por predefinição Encomenda concluída).
• Prazo de envio: número de dias de espera após o estado de disparo (predefinição: 3 dias).
• Lembrete: parte um único e-mail de lembrete se não tiver sido deixada qualquer avaliação (predefinição: 5 dias após o primeiro e-mail).

Cada e-mail contém uma ligação de avaliação pessoal com token: a avaliação deixada através dessa ligação recebe automaticamente o distintivo Compra verificada. Os envios são feitos em lotes de 50 a cada passagem do cron. O separador Request queue lista os 100 últimos pedidos com o respetivo estado (pending, sent, reminded, completed, failed, unsubscribed) e permite lançar um processamento manual.

Resumo por IA das avaliações

Assim que um produto atinge o número mínimo de avaliações publicadas (predefinição: 3), o cron gera um bloco apresentado no topo do separador de avaliações da ficha de produto: pontos fortes, pontos de atenção e síntese.

• O resumo é colocado em cache por produto e por idioma: com o Polylang ou o WPML, cada versão linguística apresenta um resumo no seu idioma.
• É regerado automaticamente quando são publicadas novas avaliações (invalidação por impressão das avaliações analisadas).
• A definição Max reviews analyzed limita o número de avaliações enviadas ao modelo.

O separador AI tools lista os resumos gerados com o idioma e a data.

Resposta automática às avaliações por IA

Cada avaliação publicada pode receber uma resposta do comerciante gerada por IA, redigida no idioma da avaliação. Definições principais:

• Modo de publicação: Rascunho (recomendado no início: cada resposta espera pela sua validação no menu Comentários) ou Publicação imediata.
• Tom: caloroso, profissional ou conciso.
• Nome de assinatura: apresentado como autor da resposta (vazio = nome do site).
• Responder às notas a partir de: 1 para responder a todas as avaliações, o que é recomendado, porque as avaliações negativas são as que mais beneficiam de uma resposta.

Salvaguardas integradas: nas notas de 3/5 ou menos, a resposta apresenta desculpas e encaminha para o apoio ao cliente, sem nunca prometer um reembolso. A resposta está limitada a cerca de 70 palavras e aparece com o distintivo Resposta oficial, excluída das médias de notas e dos rich snippets.

Fotografias, votos e código promocional de recompensa

• Fotografias dos clientes: os clientes juntam até 3 fotografias (configurável, máximo 10) à sua avaliação, nos formatos jpg, png, webp e gif, com 5 MB no máximo, apresentadas em lightbox.
• Votos de utilidade: botões «Esta avaliação foi-lhe útil?» com proteção contra duplicados por conta e por IP com hash. Nunca apresentados nas respostas do comerciante.
• Código promocional: na publicação da sua avaliação, o cliente recebe um cupão em percentagem (predefinição: 10%, 30 dias), único, de utilização única e restrito ao seu endereço de e-mail. Contra o abuso: apenas uma recompensa por e-mail e por produto.

Formulário e apresentação

• Campo de título da avaliação, opcional ou obrigatório.
• Comprimento mínimo da avaliação em carateres (predefinição: 10).
• Bloco de repartição das notas (barras de 5★ a 1★) por cima da lista de avaliações.
• Cor das estrelas personalizável (hexadecimal, predefinição #e7a11a).

Rich snippets Schema.org

O plugin conserva a marcação AggregateRating e Review nativa do WooCommerce, higienizando-a: as respostas do comerciante são excluídas da marcação e das médias, para estrelas exatas na Google. A opção pode ser desativada nas definições, o que retira então toda a marcação de avaliações.

Cron: tornar os envios fiáveis

O processamento (pedidos, lembretes, resumos por IA, respostas de recuperação) é executado de hora a hora através do WP-Cron. Como o WP-Cron só dispara quando o site é visitado, configure um verdadeiro cron de servidor para um envio fiável:

1. Copie o URL de cron com token apresentado em Settings → Cron.
2. Acrescente-o ao cron do seu alojamento (ou ao crontab), a cada 15 a 60 minutos, por exemplo com curl -s "URL" > /dev/null.

Um bloqueio anticoncorrência impede dois processamentos em simultâneo. O botão Run processing now do separador Request queue lança um processamento manual a qualquer momento.

Importação e exportação CSV

Separador Import / Export:

• Exportação: todas as avaliações de produtos com nota, título, indicador de verificação e datas.
• Importação: CSV com linha de cabeçalho e colunas product_id ou sku, author, email, rating, title, content, date (Y-m-d H:i:s, opcional), verified (1/0, opcional). As estatísticas de notas são recalculadas automaticamente após a importação.

Área de cliente

É acrescentado um separador As minhas avaliações à conta do cliente (A minha conta): cada cliente encontra aí as suas avaliações com estado de moderação, estrelas e distintivo de verificação. Se o separador devolver um erro 404 depois da ativação, volte a guardar os permalinks em Definições → Permalinks → Guardar.

RGPD e dados

• Ligação de cancelamento em cada e-mail de pedido, endereços cancelados guardados com hash SHA-256, nunca em claro.
• Endereços IP dos votantes com hash usando o salt do WordPress.
• Única chamada de saída: a API da OpenAI que controla, apenas se estiver configurada uma chave.
• A desinstalação elimina as tabelas e as definições do plugin, mas conserva todas as avaliações (avaliações nativas do WooCommerce).

Resolução de problemas

• Os pedidos não partem: verifique que a função está ativa, que há encomendas a atingir o estado de disparo, e que o cron corre (última passagem apresentada em AI tools). Configure o URL de cron do servidor.
• Sem resumo por IA: a chave da OpenAI está configurada? O número mínimo de avaliações publicadas foi atingido? O resumo é gerado na passagem do cron, e não instantaneamente.
• Sem resposta por IA: verifique o modo (em rascunho, a resposta espera em Comentários → Pendentes), a nota mínima configurada e a chave de API.
• E-mails não recebidos: o plugin envia através do mailer do WooCommerce. Teste a sua configuração global de e-mail (recomenda-se um plugin de SMTP).