Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Lorsque Sarah partage son lien d'invitation et que Marcus s'inscrit pour collecter des fonds, vous voulez que Sarah obtienne le crédit. L'attribution est ce qui rend cela possible automatiquement – sans que Sarah ait à envoyer un code à qui que ce soit, sans que Marcus ait à se souvenir de la mentionner, et sans que vous ayez à tenir une feuille de calcul de qui a recruté qui.

Cette page explique comment Charitable Ambassadors établit cette connexion – d'abord en langage clair, puis avec les détails techniques complets en bas pour les développeurs.

La version courte

Lorsque quelqu'un clique sur un lien d'invitation, un petit morceau de données (un « cookie ») est stocké dans son navigateur. Il indique à votre site, en effet : « cette personne vient de Sarah ».

Le cookie reste là tranquillement pendant 30 jours maximum. Si, pendant cette période, la personne soumet une collecte de fonds – qu'elle le fasse juste après avoir cliqué sur le lien, ou trois semaines plus tard depuis une autre page de votre site – le système lit le cookie, voit qu'elle vient de Sarah, et attribue le recrutement à Sarah.

C'est toute l'idée. Le reste de cette page n'est que les détails.

Le parcours, étape par étape

1. Sarah shares her link    >    2. Marcus clicks    >    3. Cookie stored
                                                                ↓
6. You approve, Sarah gets credit  ←  5. Marcus submits  ←  4. Marcus browses your site

1. Sarah partage son lien

Depuis sa page Mes campagnes, Sarah copie son URL d'invitation personnelle et la partage comme elle le souhaite – e-mail, SMS, réseaux sociaux, en personne. Son URL ressemble à ceci :

https://yoursite.com/?charitable-invite=jA4HZIx2AhBnouMN

La partie ?charitable-invite=… à la fin est un jeton unique qui l'identifie *elle* spécifiquement (et, si elle a utilisé un bouton de recrutement par campagne, la cause spécifique pour laquelle elle recrute).

2. Marcus clique

Le navigateur de Marcus récupère cette URL. Avant que WordPress ne rende quoi que ce soit, le gestionnaire d'URL d'Ambassadors intercepte la requête, recherche le jeton et confirme qu'il appartient à un invitant réel et actif (Sarah).

3. Le cookie est stocké

Le système dépose un petit cookie dans le navigateur de Marcus :

Propriété	Valeur
Nom	jeton_invitation_caritative
Ce qu'il contient	Le jeton de Sarah (la même chaîne que dans l'URL)
Durée de validité	30 jours
Emplacement de visibilité	Uniquement sur votre site, pas sur d'autres sites

Ce cookie est la trace. C'est ainsi que votre site se souviendra que Marcus vient de Sarah, même s'il ferme l'onglet et revient plus tard depuis une page complètement différente.

Après avoir déposé le cookie, le système redirige Marcus vers votre page de destination d'invitation – la page que vous avez configurée sous Charitable > Ambassadeurs > Invitations > Page de destination. La barre d'URL se met à jour de sorte que le paramètre ?charitable-invite=… ne soit plus visible (il n'est plus nécessaire – le cookie est là maintenant).

4. Marcus navigue sur votre site

C'est là que l'attribution devient puissante. Marcus pourrait soumettre sa collecte de fonds immédiatement, ou il pourrait :

• Lire d'abord votre page « À propos »
• Consulter la campagne de la cause en détail
• Mettre le site en favori et revenir le lendemain
• Oublier pendant une semaine, puis se souvenir soudainement et rechercher à nouveau votre site

N’importe lequel d’entre eux fonctionne toujours, tant que cela se produit dans les 30 jours et sur le même navigateur. Le cookie attend.

5. Marcus soumet sa collecte de fonds

Finalement, Marcus clique sur « Lancer une collecte de fonds » (ou sur le bouton qui mène à votre formulaire de soumission), le remplit et le soumet. Au moment où WordPress enregistre sa nouvelle collecte de fonds comme un brouillon, le gestionnaire d’attribution d’Ambassadors s’exécute :

1. Il lit le cookie charitable_invite_token du navigateur de Marcus.
2. Il recherche le jeton pour trouver l’invitant (Sarah).
3. Il appose sur la nouvelle collecte de fonds deux métadonnées : « invité par ID utilisateur = Sarah » et « via jeton = T123 ».
4. Il augmente le claim_count du jeton de Sarah de 1.

Cette marque est ce qui alimente chaque fonctionnalité de « recrue » dans Charitable Ambassadors.

6. Vous approuvez, Sarah obtient le crédit

Lorsque vous approuvez la collecte de fonds de Marcus (en la faisant passer à « publiée » – ou si vous êtes en approbation automatique, elle est publiée immédiatement), trois choses se produisent grâce à cette marque :

• La collecte de fonds de Marcus apparaît dans la vue « Vos recrues » de Sarah sur sa page Mes campagnes.
• La recrue de Marcus compte pour le widget de recrutement sur votre tableau de bord Aperçu.
• Sarah reçoit un e-mail de félicitations (« La collecte de fonds de votre recrue a été approuvée ! ») – si vous avez activé le paramètre Inviter par e-mail lors de l’approbation.

Dernier clic vs Premier clic – Que se passe-t-il lorsque quelqu’un clique sur plusieurs liens ?

Imaginez que Marcus a visité votre site deux fois :

• Jour 1 : clique sur le lien d’invitation de Sarah, lit votre site, ne s’inscrit pas.
• Jour 15 : voit le lien d’invitation de James dans un post Facebook, clique dessus, s’inscrit le jour même.

Qui obtient le crédit – Sarah ou James ?

La réponse par défaut est le dernier clic : James obtient le crédit, car c’est son lien qui a converti Marcus de « navigation » à « collecte de fonds ». C’est le modèle standard dans les systèmes de parrainage et le choix le plus courant pour les programmes de pair-à-pair.

Mais certaines organisations préfèrent l’attribution au premier clic : Sarah obtient le crédit car c’est elle qui a *introduit* Marcus à votre cause. Même si la poussée de James a été le déclencheur final, Sarah a fait le travail le plus difficile en amenant quelqu’un d’inconnu dans votre orbite.

Passer au premier clic est une seule ligne de code (voir la référence développeur ci-dessous). Le compromis est purement philosophique – il n’y a pas de bonne réponse.

Cas limites à connaître

Quelques situations se présentent régulièrement. Voici ce que le système fait dans chaque cas :

Situation	Ce qui se passe
Sarah clique sur son propre lien et essaie de s’inscrire	Protection contre l’auto-recrutement. La page de destination affiche une variante spéciale « vous ne pouvez pas vous recruter vous-même ». Même si Sarah parvient d’une manière ou d’une autre au formulaire de soumission, l’étape d’attribution l’ignore et enregistre la tentative.
Le compte de Sarah est supprimé entre le clic et l’approbation	La collecte de fonds de Marcus a toujours la métadonnée de recrue, donc le widget Aperçu le compte toujours comme une recrue – mais l’invitant s’affiche comme « (utilisateur supprimé) » et l’e-mail de félicitations n’est pas envoyé.
Sarah révoque son jeton pendant que Marcus est en cours d’inscription	L'attribution est silencieusement ignorée. La collecte de fonds de Marcus est créée normalement ; elle atterrit simplement sans crédit de recruteur.
Le cookie de 30 jours de Marcus expire avant qu'il ne soumette	La soumission n'est pas attribuée. Si Marcus clique à nouveau sur le lien de Sarah avant de soumettre, le cookie est renouvelé et l'attribution fonctionne.
Marcus clique sur le lien sur son téléphone mais s'inscrit sur son ordinateur portable	Le cookie est par appareil. Sans synchronisation de navigateur (par exemple, synchronisation Chrome), la soumission de l'ordinateur portable n'est pas attribuée.
Deux clics sur le même lien, même navigateur	Le `view_count` du jeton augmente de 1 ; l'expiration du cookie est réinitialisée à 30 jours à partir du dernier clic. Rien d'autre ne change.
Un plugin de cache sert la page de destination depuis le cache	Le système n'émet pas d'en-têtes no-cache lors de l'étape de redirection et indique au framework de cache de Pro de sauter la page de destination. Si votre plugin de cache la met toujours en cache, le cookie peut ne pas être défini – vous verrez un avis d'auto-vérification dans l'onglet d'administration des Invitations.

Où l'attribution apparaît dans votre administration

Une fois qu'un recrue a été attribué, vous le verrez à ces endroits :

• Aperçu > Widget de recrutement – compte pour Total / Approuvé / En attente / Rejeté, et pour le graphique chronologique du recrutement.
• Aperçu > Widget des meilleurs recruteurs – votre classement de ceux qui apportent le plus de recrues.
• Mes campagnes > Vos recrues (front-end, pour l'invitant) – Sarah voit Marcus dans sa liste.
• Invitations > Export CSV des meilleurs recruteurs – exporte le classement complet pour la plage de dates active.
• Invitations > Export CSV de l'activité récente – journal chronologique de chaque événement de recrutement.

Où chercher quand quelque chose semble erroné

Si une recrue n'apparaît pas là où vous l'attendez, vérifiez Outils caritatifs > Journal. Chaque événement d'attribution y écrit une entrée :

Code du journal	Ce que cela signifie
invitation_cliquée	Une URL d'invitation valide a été cliquée. Confirme que le clic a atteint votre site.
invitation_réclamée	Une soumission a été attribuée avec succès à un invitant.
auto_recrutement_ignoré	Un invitant a essayé de se recruter lui-même. Attribution ignorée.
attribution_ignorée_jeton_révoqué	Le jeton a été révoqué entre le clic et la soumission.
invitant_supprimé_lors_de_l_approbation	L'e-mail d'approbation a été ignoré car l'utilisateur de l'invitant n'existe plus.

Filtrez le journal par `source: ambassadors_invites` pour voir uniquement les entrées liées aux invitations.

---

Référence développeur

Le reste de cette page est destiné aux développeurs qui personnalisent le système d'attribution.

Le cookie

Name:      charitable_invite_token
Value:     The 16-character base62 token string
Lifetime:  30 days (filterable via charitable_ambassadors_invite_cookie_lifetime)
Path:      /
SameSite:  Lax
Secure:    true when is_ssl(), otherwise false
HttpOnly:  false (intentional - may be read by frontend analytics)

Le cookie est défini directement avec setcookie() de WP, et non via JS, il est donc disponible dès la prochaine requête.

Le gestionnaire d'URL

Charitable_Ambassadors_Invites::handle_invite_url() est accroché à init avec la priorité 1. Il :

1. Retourne immédiatement si $_GET['charitable-invite'] est vide.
2. Retourne immédiatement si is_admin() (les requêtes admin ne déclenchent pas l'attribution).
3. Recherche le jeton via Charitable_Ambassadors_Invites_Tokens::lookup_by_token().
4. Retourne immédiatement si le jeton est manquant, révoqué ou appartient à un utilisateur supprimé.
5. Définit le cookie via setcookie().
6. Appelle Charitable_Ambassadors_Invites_Tokens::increment_view( $token_id ).
7. Émet charitable_nocache_headers() (Pro 1.8.15.2+) ou nocache_headers() (solution de repli WP core).
8. Résout la page de destination via charitable_ambassadors_get_invites_setting( 'landing_page_id' ) et construit une URL de redirection avec charitable-invite supprimé.
9. wp_safe_redirect( $landing_url, 302 ) + exit.

Le code d'état 302 est délibéré afin que les couches de cache ne mémorisent pas la redirection elle-même – seulement la page de destination, qui est dynamique par charitable_is_dynamic_page.

Le gestionnaire d'attribution

Charitable_Ambassadors_Invites::on_campaign_submission_save() est accroché à l'action charitable_campaign_submission_save de Pro. Signature :

do_action( 'charitable_campaign_submission_save', $data, $campaign_id, $user_id, $form );

Le gestionnaire est adaptatif à la signature car le système de vérification l'invoque avec une ancienne forme à 2 arguments ( $fundraiser_id, $user_id ) ; en production, il reçoit toujours la forme à 4 arguments. Le gestionnaire :

1. Résout la valeur du cookie ($_COOKIE['charitable_invite_token']).
2. Retourne immédiatement s'il n'y a pas de cookie.
3. Recherche le jeton ; retourne immédiatement en cas d'absence ou de statut révoqué.
4. Protection contre l'auto-recrutement : retourne immédiatement si $token_row->inviter_user_id === (int) $user_id, enregistre self_recruit_skipped.
5. Writes the two attribution meta keys:

   update_post_meta( $campaign_id, '_charitable_ambassadors_invited_by_user_id', (int) $token_row->inviter_user_id );
   update_post_meta( $campaign_id, '_charitable_ambassadors_invited_via_token_id', (int) $token_row->token_id );
   

6. Appelle Charitable_Ambassadors_Invites_Tokens::increment_claim( $token_id ).
7. Déclenche do_action( 'charitable_ambassadors_invite_claimed', $token_row, $campaign_id, $inviter_user_id ).
8. Enregistre invite_claimed dans Outils Charitable > Journal.

Les deux clés de post-méta

Ce sont la source de vérité pour tout ce qui suit :

Clé de métadonnées	Type	Utilisé par
_charitable_ambassadors_invited_by_user_id	int (ID utilisateur WP)	Widget de recrutement, vue Vos recrues, seuil d'e-mail de l'invitant lors de l'approbation.
_charitable_ambassadors_invited_via_token_id	int (token_id PK)	Analyses au niveau du jeton. Permet de remonter une recrue à une URL spécifique et délimitée.

Ces éléments ne sont jamais supprimés par le plugin – même si l'invitant est supprimé, les métadonnées persistent (vous verrez « utilisateur supprimé » dans Meilleurs recruteurs). Pour effacer l'attribution d'une recrue spécifique, supprimez directement les entrées post_meta :

delete_post_meta( $campaign_id, '_charitable_ambassadors_invited_by_user_id' );
delete_post_meta( $campaign_id, '_charitable_ambassadors_invited_via_token_id' );

Changement du mode d'attribution

Ajoutez à functions.php de votre thème ou à un plugin spécifique au site :

add_filter( 'charitable_ambassadors_invite_attribution_mode', function () {
    return 'first_click'; // default is 'last_click'
} );

Sous first_click, le gestionnaire d'URL met toujours à jour le cookie à chaque clic (les comptages de vues sont donc précis par invitant), mais ne définit la valeur du cookie que si aucun cookie existant n'est présent. Une fois qu'un cookie est défini, les clics ultérieurs mettent à jour son expiration mais pas sa valeur.

Sous last_click (par défaut), chaque clic définit une nouvelle valeur de cookie, remplaçant tout invitant précédent.

Filtres

Filtre	Défaut	Objectif
charitable_ambassadors_invite_attribution_mode	'last_click'	Passer à 'first_click'.
charitable_ambassadors_invite_cookie_lifetime	30 * DAY_IN_SECONDS	Durée de vie du cookie en secondes.
charitable_ambassadors_invite_cookie_samesite	'Lax'	Attribut de cookie SameSite. Utilisez 'Strict' si vos URL d'invitation ne sont cliquées qu'à partir de liens sur votre propre domaine.
charitable_ambassadors_invite_self_recruit_allowed	faux	Définissez true pour désactiver la protection contre l'auto-recrutement. Non recommandé.

Actions

Action	Args	Se déclenche lorsque
charitable_ambassadors_invite_url_resolved	$token_row, $request	Après que le gestionnaire d'URL a validé le jeton, avant que le cookie ne soit défini. À utiliser pour court-circuiter (par exemple, bannir des jetons spécifiques).
charitable_ambassadors_invite_clicked	$token_row, $request	Après que le cookie a été défini.
charitable_ambassadors_invite_claimed	$token_row, $fundraiser_id, $inviter_user_id	Attribution réussie.
charitable_ambassadors_invite_self_recruit_skipped	$token_row, $fundraiser_id	Le garde d'auto-recrutement a bloqué l'attribution.
charitable_ambassadors_invite_attribution_skipped	$token_row, $reason, $fundraiser_id	Solution de repli pour tout résultat d'attribution non réussi. $reason est l'une des valeurs suivantes : 'revoked_token', 'self_recruit', 'no_cookie', 'deleted_inviter'.

Journalisation

Chaque événement d'attribution est enregistré dans Outils caritatifs > Journal via charitable_log() :

charitable_log( $code, $context, [
    'type'    => 'addon',
    'source'  => 'ambassadors_invites',
    'level'   => 'info', // or 'warning' for skip cases
    'user_id' => get_current_user_id(),
] );

Codes du journal (l'argument $code) :

Code	Niveau	Quand
invitation_cliquée	info	Le gestionnaire d'URL a résolu un jeton valide.
invitation_réclamée	info	La soumission a été attribuée avec succès.
auto_recrutement_ignoré	avertissement	Le garde d'auto-recrutement s'est déclenché.
attribution_ignorée_jeton_révoqué	avertissement	Le jeton a été révoqué entre le clic et la soumission.
invitant_supprimé_lors_de_l_approbation	avertissement	L'e-mail d'approbation a été ignoré car l'utilisateur de l'invitant n'existe plus.
unconfigured_landing_page_admin_view	info	L'administrateur a consulté l'onglet Invitations alors qu'aucune page de destination n'était configurée.

Mise en cache

La page de destination est dynamique (par utilisateur, par jeton). Le gestionnaire d'URL émet des en-têtes no-cache à chaque clic sur une invitation, et le filtre charitable_is_dynamic_page de Pro 1.8.15.2 est défini de sorte que les plugins de cache ignorent complètement la page de destination :

add_filter( 'charitable_is_dynamic_page', function ( $is_dynamic, $post_id ) {
    if ( charitable_ambassadors_is_invite_landing_page( $post_id ) ) {
        return true;
    }
    return $is_dynamic;
}, 10, 2 );

Si vous utilisez une version Pro antérieure à la 1.8.15.2 (sans le filtre charitable_is_dynamic_page), l'appel de repli nocache_headers() couvre l'étape de redirection mais n'aidera pas si un plugin de cache met en cache la page de destination directement. L'auto-vérification des invitations vous avertira de cet état.

Le tableau des jetons

Voir Comment les données d'invitation sont stockées pour le schéma complet. Les colonnes les plus pertinentes pour l'attribution :

Colonne	Type	Objectif
token_id	BIGINT PK	L'entier estampillé sur la cagnotte du filleul comme _charitable_ambassadors_invited_via_token_id.
token	VARCHAR(32)	La chaîne qui apparaît dans l'URL et le cookie.
inviter_user_id	BIGINT	L'ID utilisateur WP de l'invitant.
id_campagne	BIGINT NULL	Lorsque NON NULL, la soumission du filleul est automatiquement jointe à cette campagne parente.
statut	VARCHAR(20)	'active' ou 'revoked'. Les jetons révoqués ignorent l'attribution.
nombre_de_réclamations	INT	Augmenté de 1 à chaque attribution réussie.

Connexes

• Invitations – le document de la fonctionnalité parente.
• Comment les données d'invitation sont stockées – le cycle de vie de la table personnalisée.
• Hooks & filtres dans Ambassadors – la référence complète des filtres et actions.