Prérequis :

• Charitable Pro 1.8.16+
• Charitable Ambassadeurs 3.0.0+

La première fois que vous activez Charitable Ambassadeurs, vous verrez un écran de bienvenue qui vous demande comment vous souhaitez commencer. Il y a trois voies – toutes vous mènent au même endroit (un programme de pair-à-pair opérationnel), mais chacune correspond à un style d'utilisateur différent. Choisissez celle qui correspond à votre façon de configurer les choses et vous aurez des soumissions en cours d'exécution en quelques minutes.

Quand l'utiliser

• Configuration initiale – vous venez d'activer le plugin et souhaitez un guide à travers les paramètres importants.
• Configuration d'un deuxième site – vous savez ce que vous voulez ; choisissez un modèle pour appliquer votre configuration habituelle en un clic.
• Changement de scénario – vous avez couru un marathon l'année dernière, cette année c'est un gala. Relancer l'assistant avec le modèle Gala ré-applique les bons paramètres.
• Aider un collègue à démarrer – dirigez-le vers l'assistant afin qu'il n'ait pas à apprendre l'arborescence des paramètres.

Trouver l'assistant de configuration des ambassadeurs

L'écran de configuration apparaît automatiquement la première fois que vous visitez une page d'administration des Ambassadeurs après l'activation. Après cela :

Dans votre administration WordPress, allez à Charitable » Ambassadeurs » Général » Actions de configuration » Ouvrir la configuration

L'écran de configuration est toujours disponible – vous pouvez relancer l'une des trois voies quand vous le souhaitez, et la relance ne supprimera pas les paramètres que vous avez déjà personnalisés.

Trois voies de l'assistant

Voie 1 – Assistant

L'assistant vous guide à travers chaque paramètre important des Ambassadeurs dans un flux étape par étape. Idéal pour les personnes qui veulent voir et comprendre chaque choix avant de cliquer sur Enregistrer.

Les étapes :

#	Étape	Ce que vous décidez
1	Bienvenue	Introduction + choix de la voie.
2	Types de campagnes	Quels types de collectes de fonds vous accepterez – individuel, équipe, membre d'équipe.
3	Approbation et prérequis	Approbation manuelle ou automatique. Si les ambassadeurs doivent enregistrer un compte. S'ils doivent vérifier leur e-mail.
4	Flux de connexion	Où les ambassadeurs atterrissent lorsqu'ils doivent se connecter. (Conditionnel – ignoré si votre site a déjà un flux de connexion configuré.)
5	Pages	Créez une page /submit-campaign/ et une page /my-campaigns/ si vous ne les avez pas déjà.
6	Partage	Choisissez les réseaux sociaux que la grille de partage affiche sur les pages de collecte de fonds.
7	Style de modèle	Choisissez le rendu hérité / amélioré / visuel pour les pages de collecte de fonds.
8	Couleur de la marque	Définissez votre couleur d'accentuation principale (utilisée par les modèles améliorés + visuels). (Conditionnel – ignoré si vous restez sur les modèles hérité.)
9	Campagne de démarrage	Créez éventuellement une campagne brouillon activée pour le pair-à-pair afin d'avoir quelque chose pour tester immédiatement le flux d'ambassadeurs.
10	Terminer	Résumé de ce qui a été défini, prochaines étapes, sortie.

Chaque étape a un lien « En savoir plus sur cette étape » dans l'en-tête qui ouvre cette page de documentation ancrée au nom de l'étape. Chaque étape a également un bouton « Ignorer » pour que vous puissiez passer outre tout ce que vous préférez configurer plus tard dans les Paramètres.

Chemin 2 – Modèles

Si vous savez quel type de programme vous exécutez – un marathon, un gala, une collecte de fonds scolaire – le chemin des Modèles est le moyen le plus rapide d'appliquer un ensemble de paramètres par défaut sensé. Choisissez un modèle et l'assistant applique un ensemble de paramètres sélectionnés, puis vous place directement dans une version allégée de l'assistant pour les choix que ce modèle ne peut pas définir par défaut en toute sécurité (comme votre couleur de marque et votre campagne de démarrage).

Les six scénarios :

Modèle	Quand le choisir	Ce qu'il définit
Marathon / Marche-thon	Collectes de fonds le jour de la course avec des équipes.	Soumissions individuelles + d'équipe + de membre d'équipe, approbation manuelle, vérification par e-mail activée, mise en page « stats-forward ». Objectif de démarrage 50K $, durée 90 jours.
Mémorial / Hommage	Collectes de fonds solo en l'honneur d'une personne.	Soumissions individuelles uniquement, approbation manuelle, mise en page « story-forward ». Objectif de démarrage 10K $, durée 60 jours.
Gala annuel / Événement	Équipes internes de confiance organisant un événement annuel.	Soumissions d'équipe + de membre d'équipe, approbation automatique (faible friction), mise en page « classique ». Objectif de démarrage 100K $, durée 30 jours.
École / Éducation	Écoles primaires et secondaires, associations de parents d'élèves, collectes de fonds en classe.	Soumissions d'équipe + de membre d'équipe, approbation manuelle, mise en page « donate-first ». Objectif de démarrage 25K $, durée 45 jours.
Anniversaire / Personnel	Collectes de fonds personnelles de courte durée.	Soumissions individuelles uniquement, approbation automatique, mise en page « magazine ». Objectif de départ 1K $, durée 14 jours.
Personnalisé – Je crée le mien	Aucune des options ci-dessus ne convient.	N'applique aucun préréglage ; vous lance directement dans l'assistant habituel.

Après avoir choisi un modèle, l'assistant avance rapidement – les étapes types de campagne, approbation, partage et variante de mise en page sont déjà définies, vous ne voyez donc que Pages, Couleur de la marque, Campagne de démarrage et Terminer.

Chemin 3 – Démarrage rapide

Le chemin le plus rapide : un clic. Démarrage rapide applique un ensemble de paramètres par défaut génériques mais sensés (essentiellement le même que choisir Personnalisé et accepter tous les paramètres par défaut), crée vos pages Campagne de soumission + Mes campagnes, et vous place sur la Vue d’ensemble prêt à partager un lien d’ambassadeur.

Utilisez Démarrage rapide quand :

• Vous explorez simplement le plugin et souhaitez voir à quoi ressemble l'exécution d'ambassadeurs.
• Vous êtes un développeur qui itère sur une personnalisation et avez besoin d'une base réinitialisable.
• Vous avez déjà conçu vos propres paramètres via des filtres et ne voulez pas que les paramètres par défaut de l'assistant vous gênent.

Vous pouvez relancer l'assistant habituel à tout moment par la suite pour affiner les choix appliqués automatiquement par Démarrage rapide.

Ce que fait réellement l'assistant

Sur les trois chemins, l'assistant effectue le même type de modifications :

Surface	Ce qui est modifié
Paramètres	Clés wp_options.charitable_settings > ambassadors > * pour chaque étape que vous terminez.
Pages	L'étape Pages crée /submit-campaign/ (avec [charitable_submit_campaign]) et /my-campaigns/ (avec [charitable_my_campaigns]) en tant que brouillons s'ils n'existent pas déjà. Vous les publiez quand vous êtes prêt.
Campagne de démarrage	L'étape Démarrage crée une campagne brouillon activée pour le pair-à-pair avec une image d'en-tête et un texte de démarrage facultatifs.
État d'intégration	La progression de l'assistant est stockée dans wp_options.charitable_ambassadors_onboarding afin que vous puissiez reprendre après avoir fermé la page.

Rien n'est destructeur. Relancer l'assistant n'efface pas les paramètres existants – il vous montre la valeur existante et vous permet de la conserver ou de la modifier.

Réinitialisation des données de configuration

Si vous souhaitez repartir de zéro (par exemple, tester le flux d'intégration avant une publication), utilisez le bouton destructeur Réinitialiser les données de configuration sur Administration WordPress > Charitable > Ambassadeurs > Général > Actions de configuration. Il supprime uniquement les artefacts créés par l'assistant (l'option d'état d'intégration, les pages créées automatiquement si elles sont encore des brouillons vides, la campagne de démarrage si c'est encore un brouillon). Il ne touche pas aux paramètres.

La réinitialisation est confirmée deux fois et enregistrée.

Le panneau « La configuration nécessite une attention »

Jusqu'à ce que vous ayez terminé au moins un chemin de complétion, un panneau orange apparaît sur la Vue d’ensemble vous invitant à ouvrir la Configuration :

Vous pouvez ignorer le panneau par utilisateur – l'ignorance est stockée dans les métadonnées utilisateur et n'affecte pas les autres administrateurs.

Conseils

• Choisissez un modèle s'il convient. C'est plus rapide que l'assistant complet et vous amène à 80 % de la voie vers un site bien configuré.
• L'étape de démarrage est facultative mais recommandée. Avoir une campagne activée pour le peer-to-peer dès le premier jour signifie que vous pouvez tester vous-même le flux des ambassadeurs avant de partager quoi que ce soit publiquement.
• L'assistant n'est pas "fini pour toujours". Relancez-le quand vous voulez changer de scénario (par exemple, passer d'un gala à un programme de marathon).
• Utilisez le Démarrage rapide dans les environnements de développement. C'est le moyen le plus rapide de réinitialiser et de recommencer tout en itérant.

---

Référence développeur

Le reste de cette page est destiné aux développeurs qui personnalisent le flux d'intégration.

Stockage

wp_option:  charitable_ambassadors_onboarding
shape:      {
              'completed_via'       => null | 'wizard' | 'template' | 'quick_start',
              'completed_at'        => null | int (epoch),
              'template_slug'       => null | string,
              'current_step'        => string (key),
              'completed_steps'     => string[],
              'panel_dismissed_by'  => int[] (user IDs),
            }

L'état est lu/écrit via Charitable_Ambassadors_Onboarding_State::get_instance().

Registre des étapes

Les 10 étapes principales sont définies dans Charitable_Ambassadors_Onboarding_Steps::get_master_steps(). Chacune a un appelable can_render utilisé pour le branchement conditionnel. Deux étapes sont conditionnelles dès la sortie de la boîte :

• login_setup – ignorée si le site a déjà un flux de connexion non par défaut configuré.
• brand_color – ignorée si le site reste sur les anciens modèles (aucune couleur d'accentuation n'est utilisée).

Ajoutez, supprimez ou réorganisez les étapes via le filtre charitable_ambassadors_onboarding_wizard_steps.

can_render par étape

L'admissibilité de rendu de chaque étape peut également être remplacée via un filtre par étape :

add_filter( 'charitable_ambassadors_onboarding_step_brand_color_can_render', '__return_false' );

Utilisez ceci pour masquer des étapes individuelles sans modifier la liste principale.

Registre des modèles

Les 6 modèles sont définis dans Charitable_Ambassadors_Onboarding_Templates::get_all(). Chaque modèle a :

• label, description (affichage uniquement)
• settings – le paquet de paramètres ambassadors à appliquer
• starter – valeurs par défaut pour la campagne de démarrage (titre, description, objectif, durée, dons suggérés)

Ajoutez ou modifiez des modèles via le filtre charitable_ambassadors_onboarding_templates.

Filtres

Filtre	Défaut	Objectif
charitable_ambassadors_onboarding_wizard_steps	tableau de 10	Ajoutez, supprimez ou réorganisez les étapes de l'assistant.
charitable_ambassadors_onboarding_step_<key>_can_render	vrai	Porte conditionnelle par étape.
charitable_ambassadors_onboarding_templates	tableau de 6	Enregistrez des modèles de scénario supplémentaires.
charitable_ambassadors_onboarding_visual_template_candidates	calculé	Filtrez la liste des campagnes proposées comme modèle de campagne en mode Visuel à l’étape Style du modèle.
charitable_ambassadors_onboarding_starter_campaign_args	calculé	Modifiez les arguments wp_insert_post utilisés pour créer la campagne de démarrage. Reçoit $args, $template_slug, $data.
charitable_ambassadors_onboarding_starter_campaign_defaults	calculé	Modifiez les valeurs par défaut de la campagne de démarrage (titre, description, objectif, etc.). Reçoit $defaults, $slug.
charitable_ambassadors_onboarding_starter_suggested_donations	modèle par défaut	Remplacez les montants de don suggérés pour la campagne de démarrage. Reçoit $amounts, $template_slug.
charitable_ambassadors_onboarding_should_show_panel	calculé	Forcez l’affichage ou la masquage du panneau « Configuration nécessite une attention particulière ».
charitable_ambassadors_onboarding_panel_accent	#E38632	Couleur d’accentuation du panneau d’invite.
charitable_ambassadors_onboarding_features / _show_resources	vrai	Activez ou désactivez les sections Fonctionnalités et Ressources dans la barre latérale de l’assistant.
charitable_ambassadors_onboarding_features / _resources / _sidebar_features	calculé	Remplacez le contenu de ces sections.
charitable_ambassadors_onboarding_sidebar_illustration	SVG	Remplacez l’illustration de la barre latérale.
charitable_ambassadors_onboarding_sidebar_docs_url / _docs_label	URL wpcharitable.com	Remplacez le lien de documentation de la barre latérale.
charitable_ambassadors_onboarding_docs_url	cette page	Remplacez l’URL de base de la documentation vers laquelle les liens « En savoir plus » de chaque étape sont résolus.
charitable_ambassadors_onboarding_docs_url_for_step	calculé	Remplace l’URL de documentation par étape. Reçoit $url, $step_key.
charitable_ambassadors_onboarding_capability	gérer les paramètres de Charitable	Vérification des capacités pour tous les points de terminaison AJAX d'intégration.
charitable_ambassadors_quick_start_defaults	calculé	Remplace le lot de paramètres appliqués par Démarrage rapide.
charitable_ambassadors_onboarding_placeholder_image_meta	tableau	Métadonnées pour l'image d'en-tête de substitution utilisée par la campagne de démarrage.
charitable_ambassadors_onboarding_path_icon	SVG par chemin	Remplace l'icône par chemin dans le sélecteur de chemin. Reçoit $svg, $slug.

Actions

Action	Args	Se déclenche lorsque
charitable_ambassadors_onboarding_artifact_created	$type, $post_id	Une étape de l'assistant a créé une page ou une campagne de démarrage. $type est 'page' ou 'campaign'.
charitable_ambassadors_onboarding_complete	$via, $template_slug	L'un des trois chemins est complété. $via est 'wizard', 'template', ou 'quick_start'.
charitable_ambassadors_onboarding_quick_start_applied	–	Démarrage rapide terminé (en plus de _complete).
charitable_ambassadors_onboarding_panel_dismissed	$user_id	Un utilisateur a rejeté le panneau d'invite "Aperçu".

Points de terminaison AJAX

Tous sur wp_ajax_ uniquement, action nonce charitable_ambassadors_onboarding, capacité manage_charitable_settings (filtrable via charitable_ambassadors_onboarding_capability) :

Action	Objectif
charitable_ambassadors_onboarding_apply_quick_start	Applique le lot de valeurs par défaut du Démarrage rapide.
charitable_ambassadors_onboarding_dismiss_panel	Rejette le panneau "La configuration nécessite une attention particulière" pour l'utilisateur actuel.

(La navigation étape par étape utilise un POST de formulaire standard contre l'URL de l'assistant avec des paramètres de sous-action ; ce n'est pas de l'AJAX.)

Exemples de personnalisation

Ajouter un modèle personnalisé « Crowdfunding » :

add_filter( 'charitable_ambassadors_onboarding_templates', function ( $templates ) {
    $templates['crowdfunding'] = [
        'label'       => 'Crowdfunding launch',
        'description' => 'High-volume short-burst campaign with auto-approve.',
        'settings'    => [
            'campaign_recipients'    => [ 'individual' ],
            'auto_approve_campaigns' => 1,
            'ui_version'             => 'enhanced',
            'enhanced_layout_variant'=> 'magazine',
        ],
        'starter' => [
            'title'       => 'Help us launch',
            'description' => 'A short, intense campaign...',
            'goal'        => 20000,
            'length_days' => 30,
            'suggested_donations' => [ 10, 25, 50, 100 ],
            'terms'       => [],
        ],
    ];
    return $templates;
} );

Ignorer l’étape du flux de connexion à chaque installation :

add_filter( 'charitable_ambassadors_onboarding_step_login_setup_can_render', '__return_false' );

Remplacer la couleur d’accent du panneau de configuration pour correspondre à votre marque :

add_filter( 'charitable_ambassadors_onboarding_panel_accent', function () {
    return '#1e7e34';
} );

Connexes

• Tableau de bord de présentation – le panneau d’invite se trouve en haut de la présentation jusqu’à la fin de l’intégration.
• Afficher les fonctionnalités – les choix de l’étape de style du modèle.
• Mes campagnes – l’une des deux pages que l’étape Pages crée.
• Soumettre la campagne – l’autre page que l’étape Pages crée.
• Hooks & filtres dans Ambassadors – référence complète.