=== Adventura – Interactive Advent Calendar ===
Contributors: dimendia
Author: DIMENDIA - webdesign & internetdienstleistungen
Author URI: https://www.dimendia.de
Plugin URI: https://www.dimendia.de/apps.html
Tags: advent calendar, giveaway, quiz, sponsors, christmas
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Interactive advent calendar with 24 doors offering sponsors, prizes, quizzes and an entry form, with entries managed and winners drawn in the admin.

== Description ==

An interactive advent calendar for WordPress, built from a polished design
prototype (light, warm, modern).

* 24 doors with three states: today (open), past/participated, locked.
* Per-door entry flow: sponsor → prize → quiz → optional social → form → confirmation with a ticket number.
* Quiz without right/wrong feedback — participants only pick an answer; only the admin sees the evaluation.
* Content (sponsors, prizes, quiz questions, logos, prize images) is editable through the door editor.
* Configurable: color theme (Berry/Fir/Amber/Custom colors), layout (Grid/Staggered), door style (Tile/Circle/Gift), quiz mode (Guided/Single page).
* Custom colors: accent, background and text color freely selectable via color picker.
* Statistics dashboard with key figures and a bar chart of entries per door.
* Winner draw: random pick per door, optionally only among "all correct", winner list with CSV export.
* Email confirmation to participants (template with placeholders) and optional admin notification.
* Prevents duplicate entries: one entry per email per door.
* Entries are stored in a dedicated table; admin list with filter and CSV export.
* Progress is remembered per browser via localStorage.
* Gamification: progress bar, "streak" indicator and confetti (plus optional sound) when completing a door.
* Countdown to the next door right in the calendar header.
* Live preview in the settings: theme, colors, layout and texts are shown instantly as a mini calendar.
* Gutenberg block "Adventura" with live preview and display options in the sidebar (in addition to the shortcode).
* Newsletter integration (Mailchimp, Brevo, CleverReach) with opt-in in the form and double opt-in.
* Reminder emails via opt-in: daily WP-Cron send with one-click unsubscribe.
* Invite & refer: personal invitation link per participant, referral tracking and top referrers in the dashboard.
* Spam/cheat protection: honeypot, time trap and IP rate limit.
* GDPR tools: integration with WordPress data export and data erasure plus a suggested privacy policy text.
* GDPR-friendly: fonts are served locally, no requests to Google.

== Usage ==

Add the shortcode to a page:

`[advk_calendar]`

Optional attributes override the settings per page:

`[advk_calendar theme="tanne" layout="scene" door_style="ornament" quiz_mode="single"]`

For a preview outside December, a fixed day (1–24) can be set under
*Adventura → Settings → "Force today's door"*.

== Frequently Asked Questions ==

= Are external services (Google Fonts) loaded? =

No. The fonts used (Hanken Grotesque, Bricolage Grotesque) are served locally
from the plugin. No requests are made to Google or other third-party
servers — GDPR-friendly.

= Can participants see whether they answered correctly? =

No. The quiz intentionally shows no right/wrong feedback. The correct answer
never leaves the server; only the admin sees the evaluation.

= How do I prevent multiple entries? =

Under *Adventura → Settings → Entry* you can enable "Allow only one entry
per email per door" (default: on).

= How do I draw winners? =

Under *Adventura → Draw* a random winner is picked per door — optionally
only among participants who answered everything correctly. Winners can be
exported as CSV.

== Notes for Developers ==

When an entry is saved, the action `advk_entry_created` is fired
(parameters: entry id, day, email, ticket number, extra) — suitable for
sending a confirmation email or handing data to a CRM, for example. The fifth
parameter `extra` contains first name, last name, the opt-in flags for
newsletter and reminder, and the referral code.

== Screenshots ==

1. The advent calendar on the front end — 24 doors with today's door highlighted.
2. An opened door reveals the day's sponsor and the prize on offer.
3. A short quiz step participants answer before they can enter.
4. The entry form with consent for the terms and the privacy policy.
5. The admin settings: custom colours, header texts and a live preview.

== External services ==

This plugin does not connect to any external service by default. No data leaves
your site unless you explicitly enable and configure the optional newsletter
integration under *Adventura → Settings → Newsletter*.

When — and only when — you enable the newsletter integration, choose a provider
and enter your own API key, and a participant actively ticks the optional
newsletter opt-in checkbox, the plugin sends that participant's data to the
provider you selected so they can be added to your mailing list. The data sent
is: the participant's email address and their first and last name. It is sent
once, at the moment the entry is submitted with the opt-in checked. No data is
sent for participants who do not opt in, and nothing is sent if the integration
is disabled or no API key is set.

You can choose one of the following providers. Each is a third-party service
with its own terms and privacy policy; please review them before enabling:

* Mailchimp — email marketing service. Used to add opted-in participants to a
  Mailchimp audience/list. Data sent: email address, first name, last name.
  Terms of Use: https://mailchimp.com/legal/terms/ —
  Privacy Policy: https://www.intuit.com/privacy/statement/

* Brevo (formerly Sendinblue) — email marketing service. Used to add opted-in
  participants as a contact. Data sent: email address, first name, last name.
  Terms of Service: https://www.brevo.com/legal/termsofuse/ —
  Privacy Policy: https://www.brevo.com/legal/privacypolicy/

* CleverReach — email marketing service. Used to add opted-in participants as a
  receiver in a group. Data sent: email address, first name, last name.
  Terms of Service: https://www.cleverreach.com/en/terms-of-service/ —
  Privacy Policy: https://www.cleverreach.com/en-de/privacy-policy/

== Changelog ==

= 1.0.0 =
* First public release.
