vig-contact-ggsheet

Vig Contact Google Sheet Plugin

A Botble CMS plugin that automatically synchronizes contact form submissions to Google Sheets in real-time. When a new contact is created through your website's contact form, the plugin automatically exports the data to your configured Google Sheet.

✨ Features

• 🔄 Real-time Sync: Automatically exports contact data when new submissions are received
• 📊 Smart Headers: Automatically creates column headers in Vietnamese or English
• 🎯 Sequential Data: Appends new contacts to the next available row
• ⚙️ Easy Setup: User-friendly admin interface with step-by-step Google API configuration
• 🔒 Secure: Uses Google Service Account authentication for secure API access
• 📱 Responsive: Works with all contact form submissions across your website

🚀 Installation

1. Copy Plugin Files

   # Copy the plugin to your Botble plugins directory
   cp -r vig-contact-ggsheet platform/plugins/
   

2. Install Dependencies

   cd platform/plugins/vig-contact-ggsheet
   composer install
   

3. Activate Plugin

   • Go to Admin Panel → Plugins
   • Find "Vig Contact Google Sheet" and click Activate

⚙️ Configuration

Step 1: Create Google Service Account

1. Create Google Cloud Project

   • Visit Google Cloud Console
   • Click "Select a project" → "NEW PROJECT"
   • Enter project name (e.g., "Contact-Sheets-Integration")
   • Click "CREATE"

2. Enable Google Sheets API

   • Go to "APIs & Services" → "Library"
   • Search for "Google Sheets API"
   • Click on it and press "ENABLE"

3. Create Service Account

   • Navigate to "IAM & Admin" → "Service Accounts"
   • Click "CREATE SERVICE ACCOUNT"
   • Service account name: contact-sheets-service
   • Description: Service for syncing contact data to Google Sheets
   • Click "CREATE AND CONTINUE" → Skip permissions → "DONE"

4. Generate JSON Credentials

   • Click on your newly created service account
   • Go to "KEYS" tab
   • Click "ADD KEY" → "Create new key"
   • Select JSON format
   • Click "CREATE" (JSON file will download automatically)

Step 2: Configure Google Sheet

1. Create or Open Google Sheet

   • Create a new Google Sheet or use an existing one
   • Copy the Sheet ID from URL:

     https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID_HERE/edit
     

2. Share Sheet with Service Account

   • Click "Share" button in your Google Sheet
   • Paste the client_email from your JSON credentials file
   • Set permission to "Editor"
   • Uncheck "Notify people"
   • Click "Share"

Step 3: Configure Plugin Settings

1. Access Plugin Settings

   • Go to Admin Panel → Settings → Others → Google Sheets Integration

2. Enter Configuration

   • Google Sheet ID: Paste your sheet ID from Step 2.1
   • Google Credentials: Paste the entire JSON content from your downloaded credentials file
   • Enable Integration: Toggle to "Yes"

3. Test Connection

   • Click "Test Connection" button to verify setup
   • You should see a success message if configured correctly

📊 Data Structure

The plugin automatically creates headers and organizes data in the following columns:

🔧 How It Works

1. Event Listening: The plugin uses Laravel's Eloquent Events to listen for new contact creations
2. Smart Headers: Automatically adds Vietnamese column headers if they don't exist
3. Sequential Append: Finds the next available row and appends new contact data
4. Error Handling: Comprehensive logging and error handling for debugging
5. Real-time Sync: Data appears in Google Sheets immediately after form submission

🛠️ Technical Details

• Framework: Built for Botble CMS
• API: Uses Google Sheets API v4 with Service Account authentication
• HTTP Client: Lightweight implementation using Guzzle HTTP
• Authentication: JWT-based authentication with Google OAuth2
• Error Logging: Comprehensive logging for troubleshooting

🔍 Troubleshooting

Common Issues

❌ Connection Test Failed

• Verify Google Sheet ID is correct
• Ensure service account email has Editor access to the sheet
• Check that Google Sheets API is enabled in Google Cloud Console

❌ Permission Denied (403)

• Share your Google Sheet with the service account email (client_email from JSON)
• Ensure service account has "Editor" permissions

❌ Invalid Credentials

• Verify JSON credentials are pasted correctly in settings
• Check that the service account key is not expired

❌ Sheet Not Found (404)

• Double-check your Google Sheet ID
• Ensure the sheet exists and is accessible

Debug Mode

Enable debug logging by checking Laravel logs in storage/logs/laravel.log for detailed error information.

🔒 Security

• Uses Google Service Account for secure API access
• No user credentials are stored or transmitted
• All data is encrypted in transit using HTTPS
• Follows Google API security best practices

🆕 Version History

• v1.0.0: Initial release with basic contact sync functionality
• Real-time contact form synchronization
• Automatic header creation
• Sequential data appending
• Admin configuration interface

📝 License

This plugin is released under the MIT License. Feel free to modify and distribute according to your needs.

🤝 Support

For issues, feature requests, or contributions, please contact the development team or create an issue in the project repository.

Made with ❤️ for Botble CMS