Módulo de passatempos e sorteios para PrestaShop 8 e 9: documentação

Apresentação

O módulo dfcontest adiciona passatempos e sorteios à sua loja PrestaShop 8 ou 9. Os clientes participam automaticamente ao fazer uma encomenda, ou gratuitamente através de um formulário. O sorteio é verificável: qualquer visitante pode repetir o cálculo e obter os mesmos vencedores. O módulo gera o regulamento, envia os emails aos vencedores e recolhe a morada de entrega.

Instalação

1. No back office, abra Módulos > Gestor de módulos e clique em Carregar um módulo.
2. Carregue o ficheiro dfcontest-x.y.z.zip e clique em Instalar.
3. Aparece o menu Clientes > Passatempos. As definições gerais estão na página de configuração do módulo.

Para atualizar, basta carregar a nova versão: os scripts de atualização adicionam as colunas e as definições em falta sem mexer nos seus passatempos nem nas participações.

Configuração do módulo

Organizador

Indique a denominação social, a sede, o número de registo da empresa (NIPC, SIRET, CIF, KvK…) e o email de contacto para os participantes. Estes dados são usados no regulamento gerado e nos emails.

Apresentação

• Nome dos vencedores nas páginas públicas: só iniciais (J. S.) ou nome próprio e inicial (João S.).
• Mostrar o passatempo nas páginas dos produtos elegíveis e mostrar as participações obtidas no carrinho, com o valor que falta para a participação seguinte.
• Cor de destaque: cor da contagem decrescente, das caixas e dos contornos. Deixe vazio para o verde predefinido; os botões mantêm as cores do seu tema.
• Comprovativo de participação por email: código de participação e ligação de partilha, enviados assim que uma participação pelo formulário é válida.
• Destacar o passatempo a decorrer na página inicial (hook displayHome).

Proteção contra fraude

A opção Recusar endereços de email descartáveis bloqueia os principais serviços de email temporário (Yopmail, Mailinator, 10 Minute Mail, Guerrilla Mail e outros). O campo Outros domínios bloqueados aceita um domínio por linha; os subdomínios também são bloqueados.

Tarefas automáticas (cron)

A página de configuração mostra um URL cron assinado. Só é necessário para o piloto automático (ver abaixo). Chame-o a cada 5 a 15 minutos, por exemplo:

*/10 * * * * curl -s "https://a-sua-loja.pt/module/dfcontest/cron?token=O_SEU_TOKEN" > /dev/null

A data da última execução aparece por baixo do URL.

Criar um passatempo

Abra Clientes > Passatempos e depois Novo passatempo. O formulário está dividido em separadores.

Geral

• Nome, URL amigável, descrição e prémio (descreva cada prémio e o seu valor comercial: este texto é incluído no regulamento).
• Imagem: JPG, PNG ou WebP, 4 MB no máximo, largura recomendada de 1600 px.
• Início, fim e data de sorteio anunciada.
• Destacar na página inicial: se houver vários passatempos a decorrer, é mostrado o que termina primeiro.

Como participar

Ative a participação com compra, pelo formulário ou ambas. O máximo de participações por participante conta em conjunto as compras, o formulário e os bónus de convite, por endereço de email.

Participações por compra

• 1 participação por encomenda ou 1 participação por escalão de valor (com IVA, na moeda predefinida).
• Valor mínimo da encomenda e máximo de participações por encomenda.
• ID dos produtos elegíveis e categorias elegíveis: se estiverem definidos, só conta o valor desses produtos, com os descontos repartidos proporcionalmente. Deixe vazio para todo o catálogo.

A participação é criada quando a encomenda passa a um estado pago durante o período do passatempo. É retirada se a encomenda for cancelada, reembolsada ou tiver um erro de pagamento, enquanto as participações não estiverem seladas. Uma encomenda dividida em vários envios conta como uma só encomenda.

Participações por formulário

• Conta de cliente obrigatória: reserva o formulário aos clientes com sessão iniciada.
• Confirmação por email (recomendado): os visitantes recebem uma ligação e a participação só conta depois de confirmada.
• Número de telefone: oculto, opcional ou obrigatório.
• Pergunta: pergunta livre cuja resposta é guardada e exportada.
• Caixa de subscrição da newsletter: desmarcada por predefinição.
• Participações bónus por amigo convidado e máximo de participações bónus por participante: ativa os convites (0 desativa-os).

Sorteio

• Número de vencedores e número de suplentes (sorteados por ordem depois dos vencedores).
• Um prémio por pessoa: um participante sorteado uma segunda vez é ignorado.
• Piloto automático: selagem na data de fim, sorteio na data anunciada, emails aos vencedores (requer o URL cron).
• Substituir os vencedores que não reclamam a tempo: no fim do prazo, o vencedor é marcado como desistente e o suplente seguinte recebe o email (requer o URL cron).
• Dias para reclamar o prémio.

A impressão digital do sorteio é criada quando o passatempo é guardado pela primeira vez e não pode mudar depois. Após a selagem, as datas, as definições de participação e o número de vencedores ficam bloqueados.

Regulamento

Se ficar vazio, é gerado um regulamento em 9 artigos a partir das definições do passatempo e dos dados do organizador. Pode escrever o seu próprio texto com as variáveis {organizer}, {contest_name}, {date_start}, {date_end}, {draw_date}, {nb_winners}, {prize}, {claim_days}, {verify_url}, {commitment} e as restantes indicadas no separador.

Na loja

• /contests: lista dos passatempos a decorrer, futuros e terminados.
• Página do passatempo: contagem decrescente, prémios, formas de participar, formulário e, depois de participar, código de participação, número de participações e ligação de partilha. Depois do sorteio: lista de vencedores e aviso «Ganhou!» para o visitante em causa.
• /rules: regulamento para imprimir. /draw: página de verificação.
• Página de produto e carrinho: aviso nos produtos elegíveis e mensagem de progresso.
• Confirmação da encomenda: participações obtidas com o respetivo código.
• A minha conta > As minhas participações em passatempos: histórico, estado e botão para reclamar o prémio para os vencedores.
• Widget: na página inicial, ou em qualquer sítio com {widget name="dfcontest"} ou {widget name="dfcontest" id_contest=3}.

Desenrolar do sorteio

O painel do passatempo (botão Ver na lista) apresenta o sorteio em 4 passos.

1. Impressão digital publicada: a impressão digital SHA-256 da chave secreta é pública desde a criação do passatempo.
2. Selar as participações: disponível depois da data de fim. A lista de participações válidas é congelada e a sua impressão digital publicada. No mesmo momento, o módulo compromete-se com uma ronda futura do drand, a aleatoriedade pública da League of Entropy, publicada cerca de dois minutos depois, ou após a data de sorteio anunciada.
3. Realizar o sorteio: assim que o valor da ronda é publicado, o módulo obtém-no e sorteia os vencedores e depois os suplentes. Se o seu servidor não conseguir contactar o drand, abra a ligação drand indicada, copie o valor randomness e cole-o no campo previsto.
4. Avisar os vencedores: cada vencedor recebe um email no idioma da sua participação, com uma ligação para aceitar o prémio e indicar a morada antes do fim do prazo.

Acompanhar a entrega dos prémios

A tabela de vencedores indica para cada um: reclamado (com a morada de entrega), a aguardar resposta ou prazo ultrapassado. O botão Reenviar volta a enviar o email e reinicia o prazo. Marcar como desistente retira o prémio ao vencedor e passa-o ao primeiro suplente disponível; depois reenvie os emails para o avisar. Quando um vencedor reclama o prémio, o email de contacto do organizador recebe os seus dados.

Página de verificação

A página /draw publica a impressão digital da chave, a impressão digital da lista, a ronda drand e depois a chave, o valor público, a semente e os vencedores. Um participante pode pesquisar o seu código na lista selada e iniciar a verificação no navegador, que controla cada passo sem enviar nada para a loja. O ficheiro de prova JSON pode ser descarregado a partir da página e do painel.

Piloto automático

Para um passatempo com a opção Piloto automático, cada execução do cron:

• sela as participações quando a data de fim já passou;
• realiza o sorteio quando se atinge a data anunciada e o valor drand está publicado, e depois envia os emails aos vencedores;
• se a opção de substituição estiver ativa, marca como desistentes os vencedores cujo prazo terminou sem reclamação e avisa o suplente seguinte.

O cron não tem efeito nos passatempos sem piloto automático. Pode correr com a frequência que quiser.

Exportações e dados pessoais

• Exportar vencedores (CSV): posição, código, contactos, origem, bilhete sorteado, resposta, data do aviso, estado da reclamação e morada de entrega.
• Exportar participações (CSV): todas as participações com o estado, a origem e o consentimento para a newsletter.
• Com o módulo oficial psgdpr, a eliminação de um cliente anonimiza as suas participações e retira as dos passatempos não selados; a exportação RGPD inclui as suas participações e a reclamação do prémio.

Resolução de problemas

Uma encomenda paga não criou participação

O PrestaShop ignora os hooks de um módulo quando o perfil do funcionário que muda o estado não tem permissão para ver esse módulo. No painel do passatempo, o botão Verificar encomendas percorre as encomendas pagas do período e cria as participações em falta.

Um visitante não recebe o email de confirmação

Na página do passatempo aparece o botão Reenviar a ligação para uma participação pendente (no máximo um envio a cada dois minutos). Verifique também as definições de email da loja.

O sorteio não arranca

O valor da ronda drand só é publicado à hora indicada no painel. Depois dessa hora, se o drand continuar inacessível a partir do servidor, cole o valor randomness copiado da ligação drand.

O cron não faz nada

Verifique se o passatempo tem a opção Piloto automático e se a loja não está em modo de manutenção, que também bloqueia o URL cron. Em multiloja, chame o URL cron de cada loja.