Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

La fonctionnalité Invitations utilise une petite table de base de données personnalisée pour stocker les jetons uniques qui alimentent les URL d’invitation de vos ambassadeurs. Cette page explique où se trouve cette table, quand elle est créée, ce qu’elle contient et ce qui se passe si elle disparaît.

Si vous n’avez jamais réfléchi à la base de données de votre site auparavant, en bref : il s’agit d’une petite table bien gérée que le plugin gère automatiquement. Le reste de cette page est destiné aux cas où quelque chose d’inhabituel se produit (une mise à niveau a mal tourné, une sauvegarde ne s’est pas restaurée correctement, un administrateur demande « quelles données cette fonctionnalité stocke-t-elle ? ») et que vous avez besoin de connaître les détails.

La version courte

Question	Réponse
Qu’est-ce qui est stocké ?	Une ligne par jeton d’invitation. Chaque ligne contient la chaîne du jeton, l’ID utilisateur de l’invitant, un ID de campagne facultatif, une date de création, une date de révocation (si révoquée), un nombre de vues et un nombre de réclamations.
Où est-ce stocké ?	Dans une table personnalisée nommée <wp_prefix>charitable_ambassadors_invite_tokens (par exemple, wp_charitable_ambassadors_invite_tokens).
Quand la table est-elle créée ?	La première fois que vous activez les Invitations sur la page d’administration. Jusqu’alors, la table n’existe pas.
Des données personnelles sont-elles stockées ?	Non – juste l’ID utilisateur WordPress de l’invitant. Pas de noms, pas d’e-mails, pas d’adresses IP.

Quand la table est créée

Jusqu’à ce que vous activiez les Invitations, la table personnalisée n’existe pas – la fonctionnalité est entièrement facultative. La première fois que vous activez Activer les invitations dans Charitable > Ambassadeurs > Invitations, vous verrez une modale de confirmation unique expliquant ce qui va se passer :

« L’activation des Invitations créera une nouvelle table de base de données pour stocker les jetons d’invitation. La table est petite et utilisée uniquement par la fonctionnalité Invitations. Continuer ? »

Confirmez, et la table est créée via l’utilitaire standard dbDelta() de WordPress (le même mécanisme que tous les plugins utilisent pour gérer les tables personnalisées en toute sécurité). Le schéma est reconstruit de manière idempotente – si la table existe déjà, dbDelta() n’émet que les instructions ALTER dont il a réellement besoin.

Une ligne est également écrite dans wp_options :

charitable_ambassadors_invites_schema_version = '1.0'

C’est ainsi que le plugin sait à quelle version du schéma correspond votre table, afin que les futures mises à niveau puissent migrer proprement.

Ce qu’il y a dans la table

La table a huit colonnes – pas d’informations personnelles identifiables, pas de montants de dons, rien que l’invitant ne voit pas déjà sur sa propre page Mes campagnes :

Colonne	Ce qu’elle stocke
id	Clé primaire auto-incrémentée.
token	La chaîne unique qui apparaît dans l’URL. 16 caractères, alphanumériques.
user_id	L’ID utilisateur WordPress de l’invitant.
id_campagne	(Facultatif) Un ID de campagne parent, lorsque le jeton est limité à une cause spécifique.
created_at	Quand le jeton a été généré pour la première fois.
révoqué_à	Les quatre états d'auto-vérification
nombre_de_vues	Nombre de fois que quelqu'un a cliqué sur l'URL de ce jeton.
nombre_de_réclamations	Nombre de recrues qui se sont inscrites avec succès via ce jeton.

C'est tout. Pas d'e-mails, pas d'adresses IP, pas d'empreintes digitales de navigateur. L'invitant et le destinataire sont tous deux protégés.

Comment la table est utilisée

Trois choses se produisent avec cette table en fonctionnement normal :

1. Création de jeton – la première fois qu'un ambassadeur éligible accède à Mes campagnes avec Invitations activé, une ligne de jeton est créée pour lui (et une ligne supplémentaire pour chaque campagne parente qu'il possède).
2. Résolution de clic – lorsqu'une personne clique sur une URL d'invitation, le gestionnaire d'URL recherche le jeton pour trouver l'invitant.
3. Compteurs – nombre_de_vues est incrémenté à chaque clic ; nombre_de_réclamations est incrémenté lorsqu'une recrue est attribuée avec succès.

C'est tout le cycle de vie. Il n'y a pas de traitement en arrière-plan, pas de tâches planifiées, pas de synchronisation avec des services externes.

Les quatre états d'auto-vérification

L'onglet d'administration des Invitations dispose d'une bannière d'auto-vérification qui détecte les rares moments où quelque chose ne va pas :

Vous verrez	Ce qui ne va pas	Que faire
Rouge : « Activé mais la table de base de données est manquante »	Une mise à jour de plugin, un nettoyage manuel de la base de données ou une restauration de sauvegarde a supprimé la table alors que le paramètre est resté activé.	Cliquez sur Recréer la table – le schéma est reconstruit sur place. Aucune perte de données pour les nouveaux clics ; les anciens jetons sont perdus.
Jaune : « Schéma obsolète »	Une future mise à niveau a introduit un schéma plus récent ; votre installation n'a pas encore migré.	Cliquez sur Exécuter la mise à niveau. La migration est sûre et idempotente.
Bleu : « Désactivé mais des données existent »	Vous avez désactivé la fonctionnalité mais la table est toujours là avec des lignes de jetons dedans.	Soit Réactiver (les données reprennent leur utilisation), soit Supprimer définitivement et retirer la table (les données sont perdues à jamais).
Bleu : « Compatibilité cache désactivée »	Un plugin de cache peut mettre en cache votre page de destination d'invitation, ce qui pourrait casser l'attribution.	Activez la Compatibilité cache sous Charitable > Paramètres > Avancé > Divers.

L'auto-vérification s'exécute à chaque visite de l'onglet Invitations et dans Outils de bienfaisance > Infos sur le site. C'est ainsi que vous découvrez les problèmes de table avant qu'ils n'affectent vos clients.

Désactivation de la fonctionnalité (Désactivation douce)

Si vous décidez que les Invitations ne conviennent pas à votre programme, Désactivez les Invitations en haut de l'onglet administrateur :

• Le commutateur bascule sur désactivé.
• Le shortcode cesse de s'afficher sur la page de destination (ou affiche l'aperçu administrateur lorsqu'un administrateur la consulte).
• La carte de recrutement cesse d'apparaître sur Mes campagnes.
• Le gestionnaire d'URL cesse de traiter les clics ?charitable-invite=....
• La table reste. L'historique des jetons est conservé afin que vous puissiez le réactiver ultérieurement sans le perdre.

Ceci est réversible – réactivez à tout moment et les jetons existants reprendront leur fonctionnement.

Suppression définitive des données (Désinstallation complète)

Si vous souhaitez que les données soient supprimées – par exemple, pour la conformité RGPD ou parce que vous avez décidé de ne plus jamais utiliser les Invitations – utilisez Supprimer définitivement et supprimer la table en bas de l'onglet Invitations :

Le flux destructeur est intentionnellement en plusieurs étapes :

1. Cliquez sur Supprimer définitivement et supprimer la table.
2. Une modale de confirmation vous demande de taper le nom de la table (par exemple, wp_charitable_ambassadors_invite_tokens) pour confirmer.
3. Soumettre. La table est supprimée, l'option _schema_version est supprimée, le paramètre invites_enabled est désactivé.
4. L'action est enregistrée dans Outils de bienfaisance > Journal avec l'ID utilisateur du modérateur.

C'est une porte à sens unique. La prochaine fois que vous activerez les Invitations, une nouvelle table sera créée avec zéro ligne.

Ce qui se passe lors d'une exportation / sauvegarde

La table est une table MySQL ordinaire dans votre base de données WordPress. Tout outil qui sauvegarde les bases de données WordPress (UpdraftPlus, BackupBuddy, mysqldump, les sauvegardes automatiques de votre hébergeur) l'inclut automatiquement. Les restaurations fonctionnent de la même manière – ramenez la base de données, la table vient avec elle.

Ce qui se passe lors d'une exportation de données personnelles

L'outil d'exportation de données personnelles de WordPress exporte les données du compte WordPress de l'utilisateur. La table des Invitations stocke des références user_id, donc les jetons d'invitation d'un utilisateur sont inclus dans leur exportation de données personnelles (chaînes de jetons + décompte des vues/réclamations). Aucune donnée personnelle identifiable au-delà de l'ID utilisateur ne se trouve dans la table.

Conseils

• Ne modifiez pas manuellement la table. L'interface d'administration du plugin expose tout ce dont vous pourriez avoir besoin – révoquer un jeton, régénérer un jeton, voir les décomptes. La modification manuelle des lignes compromet l'intégrité de claim_count.
• Si vous restaurez une sauvegarde qui n'inclut pas cette table, l'auto-vérification la détectera lors de la prochaine visite de l'administrateur et proposera de recréer la table.
• Le schéma est versionné. Les futures mises à jour du plugin peuvent ajouter des colonnes ; la mise à niveau est sûre et idempotente.
• Aucun SQL dans ce document par conception. Les schémas dérivent ; les documents ne doivent pas les porter. Lisez toujours la classe Charitable_Ambassadors_Invites_Schema du plugin pour la liste canonique des colonnes.

---

Référence développeur

Le reste de cette page est destiné aux développeurs et aux administrateurs de bases de données.

Classe de schéma

Charitable_Ambassadors_Invites_Schema::table_name();        // string - prefixed name
Charitable_Ambassadors_Invites_Schema::exists();            // bool   - does the table exist
Charitable_Ambassadors_Invites_Schema::is_current();        // bool   - exists + columns match + version current
Charitable_Ambassadors_Invites_Schema::schema_version();    // string - stored version (empty if no record)
Charitable_Ambassadors_Invites_Schema::create();            // creates via dbDelta + stamps version
Charitable_Ambassadors_Invites_Schema::upgrade();           // idempotent migration to current schema
Charitable_Ambassadors_Invites_Schema::drop();              // drops table + deletes schema-version option

Toutes les méthodes sont statiques et peuvent être appelées en toute sécurité depuis n'importe quel contexte (le fichier est chargé inconditionnellement afin que le contrôle d'intégrité et les informations du site puissent interroger l'état même lorsque les Invitations sont désactivées).

Clés d'option

charitable_ambassadors_invites_schema_version       # current installed schema version
charitable_settings > ambassadors > invites_enabled # feature master switch

Classe Tokens

Pour travailler avec les lignes de la table par programme :

Charitable_Ambassadors_Invites_Tokens::get_or_create( $user_id, $campaign_id = 0 );
Charitable_Ambassadors_Invites_Tokens::lookup_by_token_string( $token_string );
Charitable_Ambassadors_Invites_Tokens::lookup_by_id( $token_id );
Charitable_Ambassadors_Invites_Tokens::increment_view( $token_id );
Charitable_Ambassadors_Invites_Tokens::increment_claim( $token_id );
Charitable_Ambassadors_Invites_Tokens::revoke( $token_id );
Charitable_Ambassadors_Invites_Tokens::build_invite_url( $token_string );

Filtres

Filtre	Défaut	Objectif
wp_charitable_ambassadors_invites	wp_charitable_ambassadors_invite_tokens	Remplacez le nom de la table (par exemple, tables dans le périmètre multisite). Non recommandé en production.
charitable_ambassadors_invitations_storage_docs_url	cette page	Remplacez l'URL de la documentation vers laquelle les bannières de contrôle d'intégrité pointent.

Actions

Action	Args	Se déclenche lorsque
charitable_ambassadors_invites_schema_created	$table_name	Schema::create() a effectivement créé (pas seulement mis à jour) la table.
charitable_ambassadors_invites_schema_upgraded	$from_version, $to_version	Schema::create() a exécuté dbDelta et appliqué des ALTER.
charitable_ambassadors_invites_schema_dropped	$table_name	Schema::drop() a supprimé la table.

Intégration des informations du site

Outils Charitable » Informations du site dispose d'un bloc Ambassadeurs qui affiche :

• Si la table existe.
• La version actuelle du schéma.
• Le nombre total de lignes.
• Si le schéma est à jour.

Voir Informations du site pour la disposition complète.

Multisite

Chaque sous-site obtient sa propre table car le nom de la table est préfixé via $wpdb->prefix. L'activation du réseau ne change rien à cela – la fonctionnalité reste opt-in par sous-site.

Export des données personnelles

La fonctionnalité Invitations enregistre un exportateur de données personnelles auprès des Outils de confidentialité de WordPress. Lorsqu'un utilisateur demande l'exportation de ses données personnelles, l'exportateur parcourt ses lignes de jetons et inclut les chaînes de jetons, les dates, les nombres de vues et les nombres de réclamations dans son export.

Capacités

Toutes les opérations d'administration (recréer, mettre à niveau, supprimer) nécessitent manage_charitable_settings. La désinstallation destructive nécessite en outre de taper le nom de la table pour confirmation.

Exemples de personnalisation

Masquer l'option de désinstallation destructive d'un rôle utilisateur spécifique :

add_filter( 'user_has_cap', function ( $allcaps, $caps, $args ) {
    if ( ! empty( $caps ) && in_array( 'manage_charitable_settings', $caps, true ) ) {
        $user = get_userdata( $args[1] );
        if ( $user && in_array( 'finance_admin', (array) $user->roles, true ) ) {
            unset( $allcaps['manage_charitable_settings'] );
        }
    }
    return $allcaps;
}, 10, 3 );

Déclenchez votre système d'audit lorsque la désinstallation destructive se déclenche :

add_action( 'charitable_ambassadors_invites_schema_dropped', function ( $table_name ) {
    wp_remote_post( 'https://audit.example.com/hook', [
        'body' => [
            'event'      => 'invites_table_dropped',
            'table_name' => $table_name,
            'user_id'    => get_current_user_id(),
            'site_url'   => site_url(),
            'timestamp'  => time(),
        ],
    ] );
} );

Redirigez les bannières d'auto-vérification vers vos documents internes :

add_filter( 'charitable_ambassadors_invitations_storage_docs_url', function () {
    return home_url( '/internal/charitable-invitations-runbook/' );
} );

Connexes

• Invitations – le document de la fonctionnalité parente.
• Comment fonctionne l'attribution – le flux clic-à-crédit.
• Informations sur le site – le bloc de diagnostic qui affiche l'état de la table.
• Hooks & filtres dans Ambassadors – référence complète.

---