Requis : Charitable Pro 1.8.16+
La géolocalisation est la couche qui transforme les latitudes/longitudes des campagnes individuelles en cartes, étiquettes de distance et recherche « trouver une campagne près de chez moi » que vous voyez sur le front-end. Depuis la version 1.8.16, elle prend en charge deux fournisseurs de cartes — OpenStreetMap (Leaflet) sans clé API, et Google Maps avec des tuiles de plus haute fidélité — et ajoute une carte de couverture des données de localisation pour que vous puissiez voir en un coup d’œil combien de vos campagnes disposent de données géographiques.
Ceci est la page des paramètres. Pour afficher une carte de ces campagnes sur le front-end, consultez la documentation du bloc Carte des campagnes.
Nouveautés de la version 1.8.16
| Changement | Ce que cela signifie |
|---|---|
| Prise en charge d'OpenStreetMap | Vous n'avez plus besoin d'une clé API Google. OpenStreetMap (rendu via Leaflet) est le nouveau défaut pour les nouvelles installations et est gratuit sans compte. |
| Sélecteur de fournisseur de carte | Un sélecteur visuel à deux cartes — OpenStreetMap (Leaflet) et Google Maps — remplace le flux de configuration précédent. |
| Carte de couverture des données de localisation | Bloc de statistiques en un coup d’œil : nombre de campagnes avec lat/lng définies, nombre avec adresse seule, nombre sans données de localisation. Comprend un lien en un clic pour filtrer la liste des campagnes vers celles qui manquent de données de localisation. |
| Autocomplétion d'adresses Nominatim | Sous OpenStreetMap, l'autocomplétion d'adresses est alimentée par le service Nominatim. Tapez deux caractères ou plus dans un champ de localisation et vous obtiendrez des suggestions — aucun compte Google requis. |
| Centre de carte par défaut | Définissez la lat/lng + le niveau de zoom auxquels la carte revient lorsqu'aucune campagne n'est visible. Le défaut est le centre géographique des États-Unis contigus (39.8283, -98.5795). |
| Champ de localisation des ambassadeurs | Lorsque le module complémentaire Ambassadeurs est actif, le formulaire public de soumission de campagne obtient un champ de localisation facultatif avec la même autocomplétion (Nominatim sous OpenStreetMap, Google Places sous Google). |
Comportement de mise à niveau : Les sites qui avaient déjà une clé API Google Places configurée au moment de la mise à niveau conservent Google Maps comme fournisseur. Les nouvelles installations (et les sites qui n'avaient aucune clé configurée) utilisent par défaut OpenStreetMap. Vous pouvez basculer entre les fournisseurs à tout moment sans perte de données — les métadonnées lat/lng des campagnes sont stockées indépendamment du fournisseur.
Où le trouver
Administration WordPress > Charitable > Paramètres > Avancé > Géolocalisation
L'onglet Avancé a des sous-onglets en haut du panneau (Reçus PDF, Géolocalisation, Multi-devises, Outils de migration, Divers). La géolocalisation est le deuxième.
La vue d'ensemble
| Partie | Objectif |
|---|---|
| Fournisseur de carte | Quel service de tuiles + autocomplétion la carte utilise. OpenStreetMap est gratuit ; Google Maps nécessite une clé. |
| Couverture des données de localisation | Résumé en lecture seule du nombre de vos campagnes pouvant être cartographiées. |
| Unité de distance par défaut | Indique si les étiquettes de distance s'affichent comme 5 miles away ou 8 km away. |
| Centre de carte par défaut | La lat/lng + le niveau de zoom auxquels la carte se fixe lorsqu'il n'y a rien à afficher. |
| Emplacement par campagne | Défini sur chaque campagne dans le Générateur de campagnes (méta _campaign_latitude, _campaign_longitude). |
| Champ d'emplacement des ambassadeurs | Capture facultative de l'emplacement lors de la soumission publique de campagne. |
Vous configurez le fournisseur une fois sur cette page. Le bloc Carte des campagnes (et le shortcode [campaigns map="1"]) affiche ensuite des cartes en utilisant le fournisseur que vous avez sélectionné.
Fournisseur de carte
Le choix du titre. Un sélecteur à deux cartes :
OpenStreetMap (Leaflet)
Aucune configuration requise, gratuit. Les tuiles proviennent des serveurs de tuiles d'OpenStreetMap ; le widget de carte est la bibliothèque open-source Leaflet. Recommandé pour la plupart des sites — il n'y a rien à enregistrer, pas de limites d'utilisation à surveiller, pas de clé à renouveler. L'autocomplétion d'adresses dans les interfaces d'administration et le formulaire Ambassadeurs est alimentée par Nominatim, le service de géocodage gratuit d'OpenStreetMap.
Une note sur l'utilisation de Nominatim : OpenStreetMap demande que les intégrations à fort volume soient polies (une requête par seconde par utilisateur, résultats mis en cache lorsque possible). L'autocomplétion de Charitable limite la saisie et met en cache les recherches, donc un site de dons à trafic normal est confortablement sous la limite.
Google Maps
Nécessite un compte Google et une clé API. Meilleure fidélité des tuiles, inclut l'imagerie satellite, et l'autocomplétion est plus rapide et plus tolérante avec les adresses partielles / mal orthographiées. Choisissez ceci si vous avez déjà standardisé vos services sur Google ou si vos cartes seront la pièce maîtresse de l'expérience.
Le passage à Google révèle le champ Clé API Google Places et un panneau Aide à la configuration avec des liens directs vers Google Cloud :
Aide à la configuration (5 étapes)
- Créer un projet Google Cloud. Le bouton ouvre
console.cloud.google.com/projectcreate. - Activer l'API Maps JavaScript et l'API Places. Le bouton ouvre la Bibliothèque d'API.
- Créer une clé API. Le bouton ouvre la page Identifiants.
- Recommandé : restreignez la clé à votre domaine (référents HTTP) et aux API Maps JavaScript + Places. Cela évite que la clé ne soit abusée si elle est divulguée.
- Collez la clé ci-dessus et cliquez sur Enregistrer.
Indicateur de connexion
Une petite pastille d'état à côté du titre Aide à la configuration reflète l'état actuel de la clé API :
| État | Ce que cela signifie |
|---|---|
| ● Non configuré | Le champ de clé est vide. Les fonctionnalités de géolocalisation qui nécessitent Google ne fonctionneront pas encore. |
| ⋯ Vérification… | La clé a été modifiée ; nous contactons Google pour vérifier. Prend 1 à 2 secondes. |
| ● Connecté | La clé est valide, les API pertinentes sont activées et votre restriction de domaine (le cas échéant) accepte le nom d'hôte de votre site. |
| ● Clé invalide — vérifiez les restrictions | La clé a été rejetée. Cause la plus fréquente : la restriction de référent HTTP sur la clé n'inclut pas votre site, ou l'API Maps JavaScript / l'API Places n'est pas activée sur le projet. Corrigez la restriction ou activez l'API et l'indicateur passera à Connecté lors du prochain chargement de la page. |
Le panneau d'aide à la configuration et le champ de clé API sont masqués lorsque OpenStreetMap (Leaflet) est sélectionné — vous pouvez basculer le fournisseur sans recharger la page et ils apparaissent/disparaissent instantanément.
Couverture des données de localisation
Une carte de statistiques en lecture seule qui résume le nombre de vos campagnes publiées qui peuvent être cartographiées :
| Stat | Ce qu'il montre |
|---|---|
| Cartographié | Campagnes avec des méta _campaign_latitude et _campaign_longitude explicites. Celles-ci s'affichent immédiatement sur la carte des campagnes. |
| Adresse uniquement | Campagnes avec une adresse postale mais sans lat/lng résolu. Elles ne s'afficheront pas sur la carte tant que l'adresse n'aura pas été géocodée — cela se produit généralement lors de la prochaine sauvegarde de la campagne, ou vous pouvez le déclencher manuellement. |
| Aucun emplacement | Campagnes sans lat/lng ni adresse. Elles n'apparaîtront jamais sur la carte tant que vous n'aurez pas ajouté de données de localisation. |
Au-dessus des statistiques se trouve une barre de progression montrant le pourcentage total de campagnes publiées qui ont une cartographie utilisable. En dessous, un lien en un clic « Voir toutes les N campagnes sans emplacement » filtre la liste d'administration des Campagnes pour n'afficher que les campagnes sans données de localisation, afin que vous puissiez les corriger par lots.
La carte se rafraîchit automatiquement chaque fois qu'une campagne est enregistrée, vous verrez donc le décompte augmenter à mesure que vous remplissez les données de localisation dans vos campagnes. Les statistiques sont mises en cache pendant une minute pour que la page des paramètres reste réactive sur les sites comportant des milliers de campagnes.
Unité de distance par défaut
Une option radio : Miles ou Kilomètres. Utilisé par les étiquettes de distance du bloc Carte des campagnes (5 miles away vs 8 km away) et tout tri par distance dans la recherche front-end. Par défaut : Miles.
Il s'agit d'un paramètre d'affichage uniquement — les calculs sous-jacents de lat/lng ne changent pas. Les sites ayant des audiences dans des pays utilisant le km devraient activer cette option ; sinon, laissez-la telle quelle.
Centre de carte par défaut
Deux champs numériques : Latitude et Longitude. La carte s'y fixe lorsqu'il n'y a rien d'autre à afficher — par exemple, lorsque le bloc Carte des campagnes est configuré pour n'afficher que les campagnes d'une catégorie qui ne contient actuellement aucune entrée, ou avant que la géolocalisation du visiteur ne se soit résolue.
Par défaut : 39.8283, -98.5795 — le centre géographique des États-Unis contigus. Pour une organisation à but non lucratif ayant la plupart de ses campagnes dans une région ou une ville, définissez plutôt ce point sur le centre de cette région afin que les rendus de carte vide semblent locaux.
Champ d'emplacement des ambassadeurs (nécessite le module complémentaire Ambassadeurs)
Lorsque le module complémentaire Charitable Ambassadors est actif et que la géolocalisation est activée, le formulaire public de soumission de campagne obtient un champ d'emplacement facultatif. Les nouveaux ambassadeurs peuvent :
- Saisir une adresse postale. L'autocomplétion suggère des correspondances (Nominatim sous OpenStreetMap, Google Places sous Google) après les deux premiers caractères, avec un délai d'environ 300 ms.
- Cliquer sur une suggestion. Le champ se remplit avec l'adresse normalisée complète ; les champs lat/lng cachés se remplissent ; la carte d'aperçu à côté du champ se recentre sur l'adresse.
- Ignorer complètement le champ — il est facultatif, sauf si vous l'avez rendu obligatoire via un filtre.
Une fois la campagne soumise, le lat/lng enregistré dans _campaign_latitude / _campaign_longitude rend la campagne immédiatement cartographiable.
Le fournisseur d'autocomplétion suit le paramètre global du fournisseur de carte : changez le site de Google à OpenStreetMap et le formulaire des Ambassadeurs change silencieusement les fournisseurs d'autocomplétion lors du prochain chargement de page.
Conseils
- Commencez avec OpenStreetMap. Évitez le travail de compte Google Cloud à moins que vous n'en ayez déjà un. Pour la plupart des sites caritatifs, la qualité des tuiles OSM est suffisante, et vous évitez une facture d'utilisation continue si vous devenez viral.
- La carte de couverture est votre liste de tâches. Si 'Adresse uniquement' est un nombre élevé, ces campagnes nécessitent que leurs adresses soient réenregistrées (ou que vous déclenchiez une géocodage en masse) ; si 'Aucun emplacement' est élevé, vous avez du travail de saisie de données à faire avant que la carte n'affiche grand-chose.
- Restreignez votre clé Google. Laisser une clé sans restriction signifie que quiconque la récupère à partir de la source de votre page peut faire grimper votre facture. Ajoutez la restriction HTTP-referrer à l'étape 4 de l'assistant d'installation ; c'est rapide et modifie significativement votre posture de risque.
- Le centre de carte par défaut n'est pas une anecdote sur la latitude/longitude. La plupart des visiteurs ne le remarqueront pas au jour le jour, mais si vous intégrez jamais la carte quelque part sans campagnes, le monde qui se stabilise dans une région sensible au lieu du milieu du Kansas est important.
- Changer de fournisseur est sûr. Changez autant de fois que vous le souhaitez. Les métadonnées Lat/lng sur les campagnes sont indépendantes du fournisseur ; seuls les services de tuiles et d'autocomplétion changent.
Référence du développeur
Métadonnées par campagne
| Clé | Type | Objectif |
|---|---|---|
_latitude_campagne |
chaîne (décimale) | La latitude enregistrée pour cette campagne. Définie automatiquement lorsqu'une adresse est géocodée ; peut être définie manuellement via Édition rapide ou par programme. |
_longitude_campagne |
chaîne (décimale) | La longitude enregistrée pour cette campagne. |
_adresse_campagne |
chaîne de caractères | Facultatif. La chaîne d'adresse d'origine saisie par le donateur / ambassadeur. Utilisée pour le re-géocodage lorsque le fournisseur change. |
Filtres
| Filtre | Défaut | Objectif |
|---|---|---|
fournisseur_carte_géolocalisation_charitable |
'leaflet' ou 'google' |
Le fournisseur de carte actif pour une requête donnée. Filtrez pour remplacer par page (par exemple, forcer OSM dans le flux Ambassadeurs même si le paramètre global est Google). |
unité_distance_par_défaut_géolocalisation_charitable |
'mi' |
L'unité utilisée dans les étiquettes de distance. |
centre_par_défaut_géolocalisation_charitable |
[39.8283, -98.5795] |
Centre de carte par défaut lat/lng. |
statistiques_couverture_géolocalisation_charitable |
(tableau) | Les statistiques de couverture des données de localisation. Filtrez pour injecter des comptes personnalisés (par exemple, si vous stockez des données de localisation dans une clé méta non standard). |
agent_utilisateur_nominatim_géolocalisation_charitable |
Nom du site + URL | La chaîne User-Agent envoyée à Nominatim. Requis par leur politique d'utilisation ; doit identifier votre site. Remplacez uniquement si vous comprenez la politique. |
clé_api_google_géolocalisation_charitable |
La clé enregistrée | La clé API Google Places a été renvoyée au code côté client. Filtrez pour conserver la clé dans un gestionnaire de secrets au lieu de la base de données. |
Actions
| Action | Quand cela se déclenche |
|---|---|
fournisseur_géolocalisation_modifié |
L'administrateur du site a enregistré un nouveau fournisseur de carte. Reçoit $old_provider, $new_provider. Accrochez-vous pour vider les caches ou déclencher le re-géocodage. |
campagne_géocodée_charitable |
L'adresse d'une campagne a été résolue avec succès en lat/lng. Reçoit $campaign_id, $lat, $lng. |
invalider_cache_statistiques_couverture_géolocalisation_charitable |
Crochet interne déclenché lorsque les données de campagne changent, pour vider le cache de la carte de couverture de 1 minute. |
Assistant de géocodage en masse
Si de nombreuses campagnes sont bloquées dans l'état Adresse uniquement (généralement parce qu'elles ont été importées), déclenchez un passage de géocodage en masse via WP-CLI :
wp charitable geolocation bulk-geocode --batch-size=20
La sortie affiche la progression par campagne et un résumé des succès / échecs à la fin. La commande en masse respecte les limites de débit du fournisseur et fait des pauses appropriées.
Exemples de personnalisation
Rendre l'emplacement obligatoire sur le formulaire de soumission de campagne des Ambassadeurs :
add_filter( 'charitable_ambassadors_submission_form_fields', function( $fields ) {
if ( isset( $fields['location'] ) ) {
$fields['location']['required'] = true;
}
return $fields;
}, 20 );
Forcer OpenStreetMap sur une page spécifique (par exemple, une intégration de carte publique) même si la valeur par défaut du site est Google :
add_filter( 'charitable_geolocation_map_provider', function( $provider ) {
if ( is_page( 'public-campaign-map' ) ) {
return 'leaflet';
}
return $provider;
} );
Récupérer la clé API Google d'un gestionnaire de secrets au lieu de la base de données :
add_filter( 'charitable_geolocation_google_api_key', function( $key_from_db ) {
if ( defined( 'GOOGLE_PLACES_KEY' ) ) {
return GOOGLE_PLACES_KEY;
}
return $key_from_db;
} );
Personnaliser le centre de carte par défaut par région :
add_filter( 'charitable_geolocation_default_center', function( $center ) {
return array( 'lat' => 51.5074, 'lng' => -0.1278 ); // London.
} );
Identifiez votre site auprès de Nominatim avec un User-Agent plus descriptif :
add_filter( 'charitable_geolocation_nominatim_user_agent', function( $ua ) {
return 'YourNonprofit (https://yournonprofit.org) - geocoding for campaign maps';
} );
Connexes
- Bloc Carte des Campagnes — Le bloc front-end qui affiche vos campagnes sur une carte réelle en utilisant ces paramètres.
- Centre de Documentation Charitable — L'index principal de la documentation.
