Ideal Surprise – Documentation

Ideal Surprise crée des calendriers à fenêtres pour Joomla, WordPress et YOOtheme Pro : calendrier de l’Avent, Saint-Valentin, Pâques, Halloween, Black Friday, jeu concours… Chaque fenêtre s’ouvre à sa date, avec un contenu, un cadeau éventuel et la collecte d’adresses e-mail avec consentement. Ce guide couvre l’installation, la création d’une campagne, l’affichage sur le site et tous les réglages.

Voir la démo ↗

Démarrage rapide en 5 minutes

Exemple : un calendrier « 7 jours, 7 cadeaux », avec la photo du lot sur chaque porte, comme dans la démo ↗.

Installer le ZIP : Système › Installer › Extensions (voir Installation).
Créer la campagne : Composants › Ideal Surprise › Campagnes › Nouveau. Donnez un titre, choisissez le modèle « Jeu concours neutre (7 jours) » et une date de début, puis Enregistrer. Les 7 fenêtres sont créées toutes seules.
Choisir qui gagne : onglet Gains, mode « Probabilité » avec une chance de gagner (par exemple 20 %), ou « Pour tous » si chaque visiteur reçoit le cadeau. Par défaut, l’adresse e-mail est demandée à la première ouverture (onglet Participation).
Remplir chaque fenêtre : bouton Fenêtres et contenu, puis la fenêtre 1. Dans Image de cette porte, choisissez la photo du lot. Ajoutez ensuite les blocs : un Titre visible par les gagnants (« Bravo, vous gagnez un sèche-cheveux »), une Image et un Texte visibles par tous, un Code cadeau visible par les gagnants, et un Texte de consolation visible par les autres. Faites de même pour les autres fenêtres.
Tester : bouton Tester, cliquez sur les fenêtres et choisissez « Gagné » ou « Perdu » pour voir les deux résultats. Rien n’est enregistré.
Afficher sur le site : un élément de menu « Calendrier Ideal Surprise », un module Ideal Surprise ou l’élément Ideal Surprise de YOOtheme Pro, puis choisissez la campagne (voir Afficher le calendrier).

Dans l’administration, l’encadré Premiers pas, en haut de la liste des campagnes, coche ces étapes au fur et à mesure et indique combien de fenêtres sont encore vides. Il disparaît quand tout est fait.

Prérequis

Joomla 4.4, 5 ou 6, PHP 8.1 ou plus (testé jusqu’à PHP 8.5)
N’importe quel template : le calendrier a son propre style et s’adapte au mobile
YOOtheme Pro 4 ou 5 pour l’élément du constructeur (facultatif)
AcyMailing pour l’inscription à une newsletter (facultatif)
L’envoi d’e-mails activé dans Joomla (Configuration globale › Serveur › Courriel) pour les e-mails aux participants
WordPress 6.2 ou plus : voir Version WordPress

Installation

Téléchargez le ZIP depuis Mes licences ou depuis le lien de l’e-mail de commande. Ne le décompressez pas.
Dans Joomla, ouvrez Système › Installer › Extensions et déposez le ZIP dans Envoyer un paquet.
Le paquet installe le composant Ideal Surprise (campagnes, participants, gagnants), le module Ideal Surprise et le plugin Système - Ideal Surprise (élément YOOtheme Pro), activé d’office. Sans YOOtheme Pro, ce plugin ne fait rien et l’installation l’indique.
Il crée aussi le groupe d’utilisateurs Ideal Surprise – Gestionnaires (voir Rôles).

Une nouvelle version s’installe de la même façon, par-dessus l’ancienne : vos campagnes, participants et gagnants sont conservés. La page À propos du composant affiche les nouveautés de chaque version.

Désinstaller

Dans Système › Gérer › Extensions, cochez seulement la ligne du paquet « Ideal Surprise » puis Désinstaller. Les campagnes et les participants sont supprimés avec le composant : exportez-les avant si vous voulez les garder.

Version WordPress

Ideal Surprise existe aussi pour WordPress, avec les mêmes campagnes, thèmes, fenêtres, cadeaux et e-mails. La même licence couvre les deux versions.

Prérequis : WordPress 6.2 ou plus, PHP 8.1 ou plus. YOOtheme Pro 4 ou 5 pour l’élément du constructeur et AcyMailing pour WordPress sont facultatifs.
Installation : téléchargez le ZIP WordPress dans « Mes licences », puis Extensions › Ajouter › Téléverser une extension, et activez-la. Le menu « Ideal Surprise » apparaît dans l’administration.
Clé de licence : collez-la dans Ideal Surprise › À propos. Les nouvelles versions arrivent ensuite dans Tableau de bord › Mises à jour.
Afficher le calendrier : le code court [ideal_surprise id="1"] (le numéro est dans la liste des campagnes), le bloc « Ideal Surprise » de l’éditeur, ou l’élément « Ideal Surprise » de YOOtheme Pro.
Extensions de cache : le calendrier demande son état au serveur à chaque visite. Si WP Rocket, LiteSpeed Cache ou une extension semblable retarde les scripts, excluez celui d’Ideal Surprise. La page À propos signale ces extensions.

Le reste de ce guide s’applique tel quel : les écrans et les réglages portent les mêmes noms. Les e-mails partent par l’envoi d’e-mails de WordPress.

Clé de licence et mises à jour

Votre clé de licence (format IDPC-XXXX-XXXX-XXXX-XXXX) figure dans l’e-mail de commande et sur la page Mes licences. Collez-la une seule fois par site :

Ouvrez Système › Mettre à jour › Sites de mise à jour.
Cliquez sur Ideal Surprise : Joomla signale « clé de téléchargement manquante ».
Collez la clé dans le champ Clé de téléchargement, puis Enregistrer et fermer.

Les nouvelles versions apparaissent ensuite dans Système › Mettre à jour › Extensions et s’installent en un clic. Les mises à jour et le support par e-mail sont inclus pendant 12 mois. Ensuite, l’extension continue de fonctionner sans limite de durée ; seul l’accès aux nouvelles versions s’arrête. Vous pouvez renouveler à tout moment depuis Mes licences.

La même clé sert pour toutes vos extensions IdealPC. Le bouton « Contacter le support » de la page À propos s’active quand une clé valide est enregistrée.

Créer une campagne

Une campagne est un calendrier : un titre, des dates, un nombre de fenêtres et un design. Ouvrez Composants › Ideal Surprise › Campagnes › Nouveau.

Modèle / thème : choisissez un des 15 thèmes, classés en trois groupes (Noël et fin d’année, Au fil de l’année, À tout moment). Le thème règle le nombre de fenêtres, les dates conseillées, la forme, les couleurs, l’effet animé et les textes.
Début : la date de la première fenêtre (obligatoire). Fin est facultative.
Rythme : une fenêtre par jour, une fenêtre par semaine, ou une date choisie pour chaque fenêtre. Heure d’ouverture : l’heure à laquelle la fenêtre du jour s’ouvre (heure du site).
Fenêtres passées : encore jouables (on peut encore gagner), consultables sans gain, ou refermées.
Enregistrer : les fenêtres sont créées automatiquement. Le bouton Fenêtres et contenu ouvre la liste des fenêtres.

Les thèmes : Calendrier de l’Avent (24 jours), Saint-Nicolas, 12 jours de Noël, Nouvel an, Saint-Valentin (14 cœurs), Carnaval, Pâques (10 œufs), Fête des mères, Fête des pères, Été / soldes, Rentrée, Halloween (7 citrouilles), Black Friday, Anniversaire de la boutique (10 ballons) et Jeu concours neutre.

Appliquer un thème à une campagne existante : choisissez un autre thème et enregistrez. Seul le design change (forme, couleurs, effet) ; les dates, les fenêtres et leur contenu sont conservés.

Date simulée (test) : affiche le calendrier comme à cette date, pour les administrateurs connectés seulement. Pratique pour tester une campagne de décembre en novembre.

Afficher le calendrier

Trois façons, au choix :

Élément de menu : Menus › Nouveau › Ideal Surprise › Calendrier Ideal Surprise, puis choisissez la campagne.
Module : Contenu › Modules site › Nouveau › Ideal Surprise, choisissez la campagne et une position.
YOOtheme Pro : dans le constructeur, ajoutez l’élément Ideal Surprise (groupe IdealPC) et choisissez la campagne. L’onglet Style change les couleurs, la forme, l’animation et l’effet pour cet élément seulement : la même campagne peut avoir un autre look sur une autre page. Un réglage vide garde le design de la campagne.

Sur un site multilingue, créez une campagne par langue (champ Langue) ou une seule campagne pour toutes les langues avec l’onglet Textes par langue.

Le contenu des fenêtres

Dans Fenêtres et contenu, cliquez sur une fenêtre. Son contenu est une pile de blocs que vous ajoutez et réordonnez : Titre, Texte, Image, Vidéo, Bouton, Code cadeau, Code unique, Séparateur ou Article Joomla.

Chaque bloc est visible par tous, seulement par les gagnants, ou seulement par les autres (message de consolation). Dans les textes, les variables {firstname}, {code} et {door} sont remplacées par le prénom, le code et le numéro de la fenêtre.

Code cadeau : le même code pour tous (par exemple NOEL10), avec une validité facultative.
Code unique : chaque gagnant reçoit un code différent, pris dans la liste Ajouter des codes uniques (un code par ligne, les doublons sont ignorés). Le nombre de codes restants est affiché.
Libellé : remplace le numéro affiché (par exemple « Lundi »). Date d’ouverture : modifiable avec le rythme « date choisie ».

La liste des fenêtres affiche le contenu, la date, le mode de gain, les lots gagnés et le nombre d’ouvertures. Remettre les gains à zéro efface les ouvertures et les gagnants des fenêtres sélectionnées (utile après des tests).

Tester avant de publier

Le bouton Tester (dans la liste des campagnes, dans la campagne et dans Fenêtres et contenu) affiche le calendrier comme sur le site, avec son design, ses textes et son image de fond. Toutes les fenêtres s’ouvrent, même celles des jours à venir, et vous choisissez le résultat à afficher : Gagné ou Perdu. Vous voyez ainsi le contenu exact d’un gagnant (avec un prénom et un code d’exemple) et le message de consolation.

Rien n’est enregistré : pas de participant, pas d’ouverture, aucun e-mail envoyé, aucun lot ni code unique utilisé. Le test fonctionne aussi avec une campagne pas encore publiée : préparez-la, testez-la, puis publiez-la.

Cadeaux, images et codes promo

Le cadeau se règle dans chaque fenêtre (Fenêtres et contenu › cliquez sur la fenêtre), avec des blocs :

Texte et Image pour présenter le lot (par exemple la photo d’un sèche-cheveux). Visible par Tous pour l’annoncer, ou Seulement les gagnants pour la surprise. La photo peut aussi aller sur la porte : champ Image de cette porte.
Code cadeau : le même code pour tous les gagnants (par exemple NOEL20).
Code unique : un code différent pour chaque gagnant, jamais donné deux fois.

Où mettre les codes uniques

Dans la fenêtre (colonne de droite, Ajouter des codes uniques) : les codes ne servent qu’à cette fenêtre.
Dans la campagne (onglet Gains, Réserve de codes uniques) : collez tous vos codes une seule fois ; chaque fenêtre avec un bloc « Code unique » y prend un code par gagnant, après ses propres codes.

Les gains suivent les codes : quand il n’y a plus de code à donner, il n’y a plus de gagnant et les participants voient le message « lots épuisés », puis la consolation.

Exemple : 5 codes promo dans une fenêtre

Ajoutez un bloc Code unique, visible par Seulement les gagnants.
Collez les 5 codes dans Ajouter des codes uniques, un par ligne.
Laissez Lots par fenêtre à 0 (= autant de lots que de codes) ou mettez 5. Enregistrez : « Codes uniques encore disponibles : 5 ».
Choisissez Instants gagnants pour répartir les 5 lots dans la journée, puis vérifiez avec Tester.

Participation et consentement

Onglet Participation de la campagne. Adresse e-mail : quand elle est demandée.

Jamais : les fenêtres s’ouvrent librement (calendrier d’information, sans gain).
À la première ouverture, puis visiteur reconnu : le visiteur s’inscrit une fois, puis ouvre les fenêtres suivantes directement.
À chaque fenêtre.
Seulement pour réclamer un gain : on ouvre librement, l’adresse est demandée seulement aux gagnants.

Les champs Prénom, Nom, Téléphone, NPA / Localité et une question libre sont masqués, facultatifs ou obligatoires. La case de consentement renvoie vers votre politique de confidentialité et votre règlement (adresse du site, par exemple /politique-de-confidentialite.html, ou adresse complète). Le texte accepté et la date sont enregistrés avec chaque participant.

Newsletter : avec AcyMailing, choisissez les listes et le texte de la case ; le double opt-in d’AcyMailing peut être activé. Envoyer le contenu par e-mail : le participant reçoit aussi le contenu de la fenêtre ouverte.

Gains et gagnants

Onglet Gains (réglage de la campagne, que chaque fenêtre peut remplacer). Mode de gain :

Pour tous : chaque participant voit le cadeau. Aucun tirage.
Instants gagnants : le serveur tire au hasard des moments secrets dans la journée (entre Gagnants à partir de et Gagnants jusqu’à) ; le premier participant après chaque moment gagne.
Probabilité : chaque ouverture a une chance de gagner en % (5 = une chance sur vingt).

Lots par fenêtre : le stock de chaque fenêtre. Quand il est épuisé, les participants voient le message « lots épuisés » puis la consolation. 0 avec « Probabilité » : sans limite. Limite de gains : combien de fois une même adresse peut gagner.

Sans bloc « Seulement les gagnants » dans une fenêtre, il n’y a rien à gagner : la fenêtre est affichée à tous et la liste des fenêtres l’indique (« Aucun lot »).

Design

Disposition : une grille (colonnes sur ordinateur, tablette et mobile, espace, forme des cases, numéros mélangés, largeur maximale) ou des fenêtres placées sur une image de votre choix.
Fenêtres : 13 formes (rectangle, coins arrondis, cercle, étoile, cœur, sapin, cadeau, œuf, maison, citrouille, feuille, soleil, ballon), animation d’ouverture (porte qui pivote, double porte, retournement, fondu, zoom), effet au survol, couleurs ou image des portes, couleur derrière la porte, bordure, couleur d’accent, fond de la fenêtre de contenu.
Numéros : format, taille (aussi sur mobile), position, police, couleur, contour, ombre et fond ; mise en avant de la fenêtre du jour.
Effets : neige, cœurs, feuilles d’automne, pétales, étoiles, bulles ou ballons, avec leur couleur, et des confettis.

Fenêtres sur une image

Onglet Disposition : choisissez Sur une image, une image de fond et ses proportions (largeur et hauteur, par exemple 16 et 9). Dans Fenêtres et contenu, le bouton Placer les fenêtres ouvre l’image : faites glisser chaque fenêtre à sa place, le carré jaune en bas à droite change sa taille (au clavier : flèches pour déplacer, Maj + flèches pour agrandir), puis Enregistrer les positions. Disposer en grille remet toutes les fenêtres en grille ; Magnétisme aligne sur une grille fine. Pour n’utiliser que quelques fenêtres, réduisez le nombre de fenêtres de la campagne. Chaque fenêtre peut avoir sa propre couleur ou sa propre image (Image de cette porte). Sur mobile : garder l’image ou passer en grille.

Tous les textes du calendrier (titre, introduction, fenêtre pas encore ouverte, formulaire, gagnant, consolation, lots épuisés…) se modifient dans l’onglet Textes, et par langue dans Textes par langue.

E-mails et notifications

Tous les e-mails se règlent dans Options (bouton en haut à droite du composant), onglet E-mails : expéditeur, adresse de réponse, logo, couleur d’accent et pied de page. Chaque e-mail peut être activé ou non, avec son objet et son texte :

Gain : au gagnant, avec son cadeau et son code.
Confirmation de participation.
Contenu de la fenêtre (si « Envoyer le contenu par e-mail » est activé dans la campagne).
Notification « Nouveau gagnant » et Notification « Nouvelle participation » : à l’administrateur.

Prévenir l’administrateur : à chaque gain, à chaque gain et à chaque nouveau participant, à chaque fenêtre ouverte, ou jamais. Les adresses de notification se règlent dans les Options ; chaque campagne peut en ajouter (Adresses à prévenir pour cette campagne). Variables : {firstname}, {lastname}, {email}, {campaign}, {door}, {code}…

Chaque participant reçoit les e-mails dans sa langue : ajoutez les traductions dans l’onglet E-mails par langue. Un bouton d’envoi de test se trouve sur la page À propos.

Participants, gagnants et export

Participants : adresse, prénom, campagne, nombre d’ouvertures et de gains, newsletter, date d’inscription. Gagnants : date, fenêtre et code de chaque gain. Les deux listes se filtrent par campagne et s’exportent en CSV (compatible Excel).

Pour répondre à une demande de suppression (droit à l’oubli), cochez le participant et Supprimer : ses ouvertures sont supprimées avec lui.

Sécurité et anti-triche

Options, onglet Sécurité :

Ouvertures max. par heure et par connexion et par jour et par adresse.
Une boîte = une participation : nom+1@… et nom@… (et les points dans une adresse Gmail) comptent comme la même adresse.
Domaines refusés : par exemple les adresses jetables.

Le tirage se fait sur le serveur : le contenu d’un gain n’est jamais envoyé au navigateur avant le résultat, et deux ouvertures simultanées ne peuvent pas prendre le même lot.

Diagnostic et débogage

La page À propos contient un Diagnostic : YOOtheme Pro et le plugin de l’élément, campagnes publiées, où les calendriers sont affichés, heure du site, cache de page, optimiseurs (JCH Optimize, LiteSpeed Cache…), envoi d’e-mails, notifications, mode débogage et version de PHP. Vert : tout va bien · bleu : pour information · orange : à vérifier · rouge : à corriger. Les dernières erreurs du journal administrator/logs/idealsurprise.php sont affichées dessous.

Mode débogage (Options › Avancé) : « Administrateurs connectés au site » ou « Tout le monde (test temporaire) ». Un bandeau au-dessus du calendrier indique la campagne, l’heure du serveur, les modes, le nombre de fenêtres et si le script est bien chargé ; la console du navigateur détaille chaque étape. Si le script n’est pas chargé, c’est souvent un optimiseur qui le retarde ou le combine : excluez media/com_idealsurprise/ de l’optimiseur.

Si le calendrier ne change pas après une modification, videz le cache de Joomla et celui de l’optimiseur.

Rôles et langues

Le groupe Ideal Surprise – Gestionnaires (créé à l’installation) peut se connecter à l’administration et gérer les campagnes, les fenêtres et les participants, sans accès au reste du site. Ajoutez-y un utilisateur dans Utilisateurs › Gérer. Les droits se règlent aussi dans Options › Droits.

L’interface, les textes du calendrier et les e-mails sont fournis en français, anglais, allemand et italien.