Documentation technique

Intégrer CleanCity sur votre site

Une carte de signalement propreté/voirie embarquable en une ligne, sur le site de votre mairie ou dans votre application. Vos citoyens signalent directement sans quitter votre page ; les signalements créés apparaissent immédiatement dans le Dashboard et l'application terrain CleanCity.

Aperçu ci-dessus en mode démonstration — données fictives, aucune connexion à une vraie commune.

Trouvez le code INSEE de votre commune

Le code ci-dessous doit contenir le code INSEE (5 caractères) de votre commune, pas son code postal. Tapez son nom pour le récupérer et le voir s'appliquer automatiquement dans les exemples de code plus bas.

Intégration en une ligne

Ajoutez ce code à l'endroit de votre page où la carte doit apparaître. Remplacez 75118 par le code INSEE de votre commune (ou utilisez la recherche ci-dessus).

<div id="cleancity-widget" data-city="75118" data-height="640"></div>
<script src="https://clean-city.fr/js/cleancity-embed.js" defer></script>

Intégration manuelle (iframe)

Si vous préférez ne pas charger de script tiers, une simple iframe suffit :

<iframe
  src="https://clean-city.fr/widget.html?city=75118"
  width="100%" height="640" style="border:0;border-radius:12px"
  allow="geolocation; camera"
  referrerpolicy="strict-origin-when-cross-origin"
  title="Signaler un problème de propreté - CleanCity"
  loading="lazy"></iframe>

Point le plus souvent oublié : l'attribut allow="geolocation; camera". Sans lui, le navigateur refuse la géolocalisation à l'iframe quelle que soit la configuration de CleanCity.

Paramètres

Paramètre	Obligatoire	Valeurs	Effet
`city`	Oui	Code INSEE (5 car.)	Commune scopée pour cette instance, non modifiable par le visiteur
`lat`, `lng`	Non	Décimal	Centre initial de la carte (recommandé : le centre de votre commune)
`zoom`	Non	10 à 18	Niveau de zoom initial (défaut 14)
`mode`	Non	`full`, `readonly`, `demo`	`readonly` : carte seule, sans création. `demo` : données fictives

Dimensions recommandées

Le widget occupe toute la hauteur de son conteneur — pas de redimensionnement automatique une fois posée (une carte, contrairement à un formulaire, n'a pas de hauteur "naturelle" : la laisser se redimensionner selon le contenu la comprimerait à une hauteur inutilisable dès qu'on change d'écran).

Avec cleancity-embed.js, la hauteur par défaut s'adapte automatiquement à la largeur d'écran au chargement : 480px sur mobile (≤480px de large), 560px sur tablette (≤768px), 640px sur ordinateur. L'attribut data-height reste prioritaire si vous préférez fixer une valeur vous-même. En intégration iframe manuelle, choisissez la hauteur explicitement (aucune détection automatique dans ce cas). Largeur minimale supportée : 320px.

Intégration dans une application (WebView)

Le widget est une page web autonome, chargeable dans une WebView Android ou une WKWebView iOS exactement comme dans un navigateur. Prérequis côté application hôte :

JavaScript et le stockage local (cookies/IndexedDB) activés
Géolocalisation activée avec permission plateforme accordée si vous souhaitez proposer le bouton de localisation optionnel (Android : setGeolocationEnabled(true) + onGeolocationPermissionsShowPrompt ; iOS : déclarer NSLocationWhenInUseUsageDescription)
Ouverture des liens externes (mentions légales, confidentialité) dans le navigateur système plutôt que dans la WebView

Événements

Le widget envoie des messages postMessage à la page parente. Tous portent { source: 'cleancity-widget', version: 1, type, payload } — vérifiez toujours event.origin === 'https://clean-city.fr' avant d'utiliser le contenu.

Type	Payload	Quand
`cleancity:ready`	`{ city }`	Widget initialisé et authentifié
`cleancity:report-created`	`{ reportId, categoryId, city }`	Signalement créé (aucune coordonnée précise ni donnée personnelle)
`cleancity:error`	`{ code, message }`	Erreur exposable à l'utilisateur

Avec le script d'intégration cleancity-embed.js, ces événements sont relayés en CustomEvent DOM sur votre conteneur :

document.getElementById('cleancity-widget')
  .addEventListener('cleancity:report-created', (e) => {
    console.log('Nouveau signalement', e.detail);
  });

Confidentialité et responsabilités

Le widget fonctionne avec un compte citoyen anonyme (aucune inscription requise), comme l'application CleanCity. AiVeil est responsable du traitement pour le volet communautaire (comptes citoyens, gamification) ; votre commune reste responsable du traitement pour le volet municipal (signalements transmis à vos services), AiVeil agissant comme sous-traitant au sens de l'article 28 du RGPD dans le cadre d'un contrat/DPA signé.

La marque CleanCity reste toujours visible dans le pied du widget ("Propulsé par CleanCity") — elle ne peut pas être masquée ni remplacée par un logo tiers.

Politique de confidentialité complète : clean-city.fr/confidentialite.html. Pour toute question d'intégration : contact@clean-city.fr.