Widget Avis Google

Widget JavaScript pour afficher les avis Google de votre établissement avec mise à jour automatique via l'API Google Places.

Fonctionnalités

• Affichage responsive des avis Google
• Mise à jour automatique via l'API Google Places
• Cache de 1 semaine (configurable) pour minimiser les appels API
• Retourne toujours le fichier JSON existant
• Mise à jour silencieuse en arrière-plan si le cache est expiré
• Avatars avec initiales et gradients colorés
• Bouton "Lire plus" pour les avis longs
• Chargement progressif des avis

Prérequis

• PHP 7.4 ou supérieur
• Extension PHP cURL activée
• Une clé API SerpApi (gratuit : 100 recherches/mois)
• Le Place ID de votre établissement Google

Installation

1. Obtenir les credentials API

Clé API SerpApi

1. Créez un compte gratuit sur SerpApi
2. Copiez votre clé API depuis le dashboard
3. Plan gratuit : 100 recherches/mois (largement suffisant avec cache)

Avantages :

• ✅ Jusqu'à 50+ avis Google
• ✅ Données complètes (texte, avatars, liens)
• ✅ 100 recherches gratuites/mois
• ✅ Avec cache hebdomadaire = seulement ~4 requêtes/mois

Place ID Google

Pour trouver votre Place ID :

1. Allez sur Place ID Finder
2. Recherchez votre établissement
3. Copiez le Place ID (commence par ChIJ...)

2. Configuration

1. Copiez le fichier de configuration :

cp config.example.php config.php

2. Éditez config.php et ajoutez vos credentials :

define('SERPAPI_KEY', 'votre_clé_serpapi');  // Clé SerpApi
define('GOOGLE_PLACE_ID', 'ChIJ...');        // Place ID de votre établissement
define('CACHE_DURATION', 604800);            // 1 semaine en secondes
define('MAX_REVIEWS', 50);                   // Nombre maximum d'avis à afficher
define('MIN_RATING', 4);                     // Note minimum (1-5 étoiles)

3. Assurez-vous que config.php est bien dans .gitignore pour ne pas exposer vos credentials

Configuration du cache

La durée du cache détermine la fréquence des appels à l'API Google. Valeurs courantes :

define('CACHE_DURATION', 604800);  // 1 semaine (recommandé)
define('CACHE_DURATION', 86400);   // 1 jour
define('CACHE_DURATION', 259200);  // 3 jours
define('CACHE_DURATION', 1209600); // 2 semaines

Plus la durée est longue, moins vous consommez de quota API Google.

Configuration des filtres d'avis

Vous pouvez contrôler quels avis sont affichés :

Nombre maximum d'avis

define('MAX_REVIEWS', 10);    // Afficher maximum 10 avis
define('MAX_REVIEWS', 5);     // Afficher maximum 5 avis
define('MAX_REVIEWS', null);  // Pas de limite (afficher tous les avis)

Note : SerpApi permet d'obtenir jusqu'à 50+ avis (bien plus que les 5 avis de l'API Google Places classique)

Note minimum

Filtrez les avis par note d'étoiles (1-5) :

define('MIN_RATING', 5);  // Uniquement les avis 5 étoiles
define('MIN_RATING', 4);  // Avis 4 et 5 étoiles (recommandé)
define('MIN_RATING', 3);  // Avis 3, 4 et 5 étoiles
define('MIN_RATING', 1);  // Tous les avis (pas de filtre)

Exemple de configuration pour afficher uniquement les meilleurs avis :

define('MAX_REVIEWS', 6);   // Maximum 6 avis
define('MIN_RATING', 5);    // Uniquement les 5 étoiles

Si vous avez 10 avis dont 7 avec 5 étoiles et 3 avec 4 étoiles, seuls les 6 premiers avis 5 étoiles seront affichés.

Utilisation

Récupérer les avis

Le fichier index.php retourne toujours le contenu de reviews.json et met à jour le fichier automatiquement si nécessaire.

# Appel normal - retourne reviews.json et màj automatique si besoin
curl http://localhost/widget_google_reviews/index.php

Comportement

1. Fichier n'existe pas :

   • Appelle automatiquement SerpApi
   • Crée reviews.json
   • Retourne les avis

2. Cache valide (fichier < 1 semaine) :

   • Retourne immédiatement reviews.json
   • N'appelle PAS l'API
   • Économise votre quota

3. Cache expiré (fichier > 1 semaine) :

   • Appelle automatiquement SerpApi
   • Met à jour reviews.json
   • Retourne le nouveau contenu

4. Erreur API :

   • Retourne quand même reviews.json existant
   • Logs l'erreur dans la réponse
   • Vos visiteurs voient toujours des avis

Réponse API

{
  "success": true,
  "api_called": false,
  "reviews": [...],
  "count": 5,
  "file_age_seconds": 345600,
  "next_update_timestamp": 1730476800,
  "cache_duration_seconds": 604800,
  "timestamp": "2025-10-31T16:00:00+01:00"
}

Champs de la réponse :

• api_called: true si l'API Google a été appelée lors de cette requête
• file_age_seconds: Âge du fichier en secondes
• next_update_timestamp: Timestamp Unix de la prochaine mise à jour
• cache_duration_seconds: Durée du cache configurée

Erreur

{
  "success": false,
  "error": "Message d'erreur",
  "timestamp": "2025-10-31T16:00:00+01:00"
}

Format des avis

Chaque avis dans le tableau reviews contient :

{
  "id": 1,
  "author": "Nom de l'auteur",
  "avatar": "https://lh3.googleusercontent.com/...",
  "date": "il y a 2 mois",
  "rating": 5,
  "text": "Texte de l'avis..."
}

Structure des fichiers

widget_google_reviews/
├── index.php           # API pour récupérer les avis Google
├── config.php          # Configuration (à créer, non versionné)
├── config.example.php  # Exemple de configuration
├── reviews.json        # Cache des avis (mis à jour automatiquement)
├── index.html          # Widget HTML
├── script.js           # Logique du widget
├── styles.css          # Styles du widget
├── .gitignore          # Fichiers à ignorer
└── README.md           # Documentation

Optimisation des coûts API

Le système est conçu pour minimiser les appels API et donc les coûts :

• Cache de 1 semaine par défaut = ~4 appels API par mois
• Le widget JavaScript lit reviews.json localement (pas d'appel API)
• Seul index.php appelle l'API (et seulement si cache expiré)
• En cas d'erreur API, continue d'afficher les anciens avis

Exemple de coûts

Avec CACHE_DURATION = 604800 (1 semaine) :

• 4 appels API par mois
• ~48 appels API par an
• Bien en dessous du quota gratuit Google (généralement des milliers)

Automatisation (optionnel)

Le cache automatique rend les cron jobs optionnels. Le fichier se met à jour automatiquement quand un visiteur charge la page et que le cache est expiré.

Cependant, si vous voulez garantir des données fraîches avant qu'un visiteur n'arrive, vous pouvez configurer un cron job :

# Mise à jour hebdomadaire (dimanche à 2h du matin)
0 2 * * 0 curl -s "https://votre-domaine.com/widget_google_reviews/index.php" > /dev/null

Ou avec PHP CLI :

0 2 * * 0 /usr/bin/php /chemin/vers/widget_google_reviews/index.php

Note : Avec le système de cache automatique, un cron n'est généralement pas nécessaire.

Limitations de l'API

SerpApi

• ✅ Jusqu'à 50+ avis disponibles
• ✅ Plan gratuit : 100 recherches/mois
• ✅ Avec cache hebdomadaire = seulement ~4 recherches/mois
• ✅ Données complètes (texte intégral, avatars, liens profils)
• ⚠️ Service tiers (pas d'API officielle Google)

Sécurité

• Ne versionnez JAMAIS votre config.php
• Restreignez votre clé API aux domaines autorisés
• Utilisez HTTPS en production
• Définissez display_errors à 0 en production dans config.php

Dépannage

"API credentials not configured"

Vérifiez que config.php existe et contient les bonnes valeurs.

"API Error: REQUEST_DENIED"

Vérifiez que :

• L'API Places est activée dans Google Cloud Console
• Votre clé API est valide
• Les restrictions de domaine autorisent votre domaine

"Failed to write to file"

Vérifiez les permissions d'écriture sur reviews.json :

chmod 644 reviews.json

Support

Pour toute question ou problème, consultez :

• Documentation Google Places API
• Guide des Place IDs

Licence

MIT