Giveaway and contest module for PrestaShop 8 and 9: documentation

Overview

The dfcontest module adds giveaways and contests to your PrestaShop 8 or 9 store. Customers enter automatically when they order, or for free through a form. The prize draw is verifiable: any visitor can redo the calculation and get the same winners. The module generates the official rules, emails the winners and collects their delivery address.

Installation

1. In the back office, open Modules > Module Manager and click Upload a module.
2. Upload the dfcontest-x.y.z.zip file, then click Install.
3. The Customers > Contests menu appears. General settings are on the module configuration page.

To update, simply upload the new version: the upgrade scripts add missing columns and settings without touching your contests or entries.

Module configuration

Organizer

Enter the legal company name, registered address, company registration number (SIRET, CIF, Handelsregister, KvK…) and the contact email for participants. This information feeds the generated rules and the emails.

Display

• Winner names on public pages: initials only (J. D.) or first name and initial (John D.).
• Show the contest on eligible product pages and show earned entries in the cart, with the amount missing for the next entry.
• Accent colour: colour of the countdown, boxes and borders. Leave empty for the default green; buttons keep your theme colours.
• Entry receipt by email: entry code and share link sent as soon as a form entry is valid.
• Feature the running contest on the home page (displayHome hook).

Fraud protection

The Refuse disposable email addresses option blocks the main temporary email services (Yopmail, Mailinator, 10 Minute Mail, Guerrilla Mail and others). The Other blocked domains field takes one domain per line; subdomains are blocked too.

Automatic tasks (cron)

The configuration page shows a signed cron URL. It is only needed for autopilot (see below). Call it every 5 to 15 minutes, for example:

*/10 * * * * curl -s "https://your-store.com/module/dfcontest/cron?token=YOUR_TOKEN" > /dev/null

The date of the last run is shown under the URL.

Creating a contest

Open Customers > Contests, then New contest. The form is split into tabs.

General

• Name, friendly URL, description and prize (describe each prize and its retail value: this text is used in the rules).
• Image: JPG, PNG or WebP, 4 MB maximum, 1600 px wide recommended.
• Start, end and announced draw date.
• Feature on the home page: when several contests are running, the one ending first is shown.

How to enter

Enable entry with a purchase, through the form, or both. The maximum entries per participant counts purchases, form and referral bonuses together, per email address.

Purchase entries

• 1 entry per order or 1 entry per amount spent (tax included, in the default currency).
• Minimum order amount and maximum entries per order.
• Eligible product IDs and eligible categories: when set, only the amount of these products counts, with discounts spread proportionally. Leave empty for the whole catalogue.

An entry is created when the order moves to a paid status during the contest period. It is removed if the order is cancelled, refunded or in payment error, as long as the entries are not sealed. An order split into several shipments counts as one order.

Form entries

• Customer account required: limits the form to signed-in customers.
• Confirm by email (recommended): guests receive a link and their entry only counts once confirmed.
• Phone number: hidden, optional or required.
• Question: free question whose answer is stored and exported.
• Newsletter opt-in checkbox: unchecked by default.
• Bonus entries per invited friend and maximum bonus entries per participant: enables referral (0 disables it).

Draw

• Number of winners and number of reserve winners (drawn in order after the winners).
• One prize per person: a participant drawn a second time is skipped.
• Autopilot: sealing at the end date, draw on the announced date, winner emails (cron URL required).
• Replace winners who do not claim in time: at the end of the claim period, the winner is marked as forfeited and the next reserve is emailed (cron URL required).
• Days to claim the prize.

The draw fingerprint is created when the contest is saved for the first time and cannot change afterwards. After sealing, dates, entry settings and number of winners are locked.

Rules

If left empty, 9-article rules are generated from the contest settings and the organizer details. You can enter your own text with the variables {organizer}, {contest_name}, {date_start}, {date_end}, {draw_date}, {nb_winners}, {prize}, {claim_days}, {verify_url}, {commitment} and the others listed in the tab.

In the store

• /contests: list of running, upcoming and finished contests.
• Contest page: countdown, prizes, ways to enter, form, then entry code, number of entries and share link once entered. After the draw: winner list and a “You won” banner for the visitor concerned.
• /rules: printable rules. /draw: verification page.
• Product page and cart: banner on eligible products and progress message.
• Order confirmation: entries earned with their code.
• My account > My contest entries: history, status and prize claim button for winners.
• Widget: shown on the home page, or anywhere with {widget name="dfcontest"} or {widget name="dfcontest" id_contest=3}.

Draw process

The contest dashboard (View button in the list) presents the draw in 4 steps.

1. Commitment published: the SHA-256 fingerprint of the secret key has been public since the contest was created.
2. Seal the entries: available after the end date. The list of valid entries is frozen and its fingerprint published. At the same time, the module commits to a future round of drand, the public randomness of the League of Entropy, published about two minutes later, or after the announced draw date.
3. Run the draw: as soon as the round value is published, the module fetches it and draws the winners then the reserves. If your server cannot reach drand, open the drand link shown, copy the randomness value and paste it in the field provided.
4. Notify the winners: each winner receives an email in the language of their entry, with a link to accept the prize and give their address before the deadline.

Tracking prize delivery

The winners table shows for each one: claimed (with the delivery address), waiting for reply or claim period over. The Resend button sends the email again and restarts the claim period. Mark as forfeited takes the prize from the winner and gives it to the first available reserve; then send the emails again to notify them. When a winner claims their prize, the organizer contact email receives their details.

Verification page

The /draw page publishes the key fingerprint, the list fingerprint, the drand round, then the key, the public value, the seed and the winners. A participant can search for their code in the sealed list and run the check in their browser, which verifies each step without sending anything to the store. The JSON proof file can be downloaded from the page and from the dashboard.

Autopilot

For a contest with the Autopilot option, each cron run:

• seals the entries once the end date has passed;
• runs the draw when the announced date is reached and the drand value is published, then emails the winners;
• if the replacement option is on, marks as forfeited the winners whose claim period ended without a claim and emails the next reserve.

The cron has no effect on contests without autopilot. It can run as often as you like.

Exports and personal data

• Export winners (CSV): rank, code, contact details, source, drawn ticket, answer, notification date, claim status and delivery address.
• Export entries (CSV): all entries with their status, source and newsletter consent.
• With the official psgdpr module, deleting a customer anonymizes their entries and withdraws those of unsealed contests; the GDPR export includes their entries and prize claim.

Troubleshooting

A paid order did not create an entry

PrestaShop skips a module’s hooks when the profile of the employee changing the status is not allowed to view that module. In the contest dashboard, the Check orders button goes through the paid orders of the period and creates the missing entries.

A guest does not receive the confirmation email

On the contest page, the Send the link again button appears for a pending entry (one email every two minutes at most). Also check the store’s email settings.

The draw will not start

The drand round value is only published at the time shown in the dashboard. After that time, if drand remains unreachable from the server, paste the randomness value copied from the drand link.

The cron does nothing

Check that the contest has the Autopilot option and that the store is not in maintenance mode, which also blocks the cron URL. In multistore, call the cron URL of each store.