# Google Maps API Configuration Guide

Complete guide for configuring Google Maps API to remove the developer watermark and enable full map functionality in the EventBookings WordPress plugin.

---

## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Google Cloud Console Setup](#google-cloud-console-setup)
3. [Enable Required APIs](#enable-required-apis)
4. [Create API Key](#create-api-key)
5. [Configure API Key Restrictions](#configure-api-key-restrictions)
6. [Update Plugin Configuration](#update-plugin-configuration)
7. [Testing & Verification](#testing--verification)
8. [Troubleshooting](#troubleshooting)

---

## Prerequisites

- Google account (Gmail)
- Access to Google Cloud Console
- Credit/debit card for billing verification (free tier available)
- WordPress site domain name

---

## Google Cloud Console Setup

### Step 1: Access Google Cloud Console

1. Go to https://console.cloud.google.com/
2. Sign in with your Google account

### Step 2: Create a New Project (or Select Existing)

**Create New Project:**
1. Click the project dropdown at the top of the page
2. Click "New Project"
3. Enter project details:
   - **Project name**: `EventBookings-Maps` (or your preferred name)
   - **Organization**: Leave default or select your organization
4. Click "Create"
5. Wait for project creation (30-60 seconds)
6. Select the newly created project from the dropdown

**OR Select Existing Project:**
1. Click the project dropdown
2. Select your existing project

### Step 3: Enable Billing

**IMPORTANT:** Billing must be enabled even if using the free tier.

1. Click the hamburger menu (☰) → **Billing**
2. If no billing account exists:
   - Click "Link a billing account"
   - Click "Create billing account"
   - Enter billing information (credit/debit card)
   - Accept terms and conditions
   - Click "Start my free trial" or "Submit and enable billing"
3. If billing account exists:
   - Click "Link a billing account"
   - Select your billing account
   - Click "Set account"

**Free Tier Information:**
- Google Maps provides $200 free credit per month
- Covers approximately 28,000 map loads per month
- No automatic charges without explicit upgrade

---

## Enable Required APIs

### Step 1: Navigate to API Library

1. Click hamburger menu (☰) → **APIs & Services** → **Library**
2. Or visit: https://console.cloud.google.com/apis/library

### Step 2: Enable Maps JavaScript API

1. Search for "Maps JavaScript API"
2. Click on **Maps JavaScript API**
3. Click **Enable** button
4. Wait for activation (10-20 seconds)

### Step 3: Enable Places API

1. Click "Library" in the left sidebar
2. Search for "Places API"
3. Click on **Places API**
4. Click **Enable** button
5. Wait for activation (10-20 seconds)

### Step 4: Verify APIs are Enabled

1. Click hamburger menu (☰) → **APIs & Services** → **Enabled APIs & Services**
2. Confirm both APIs are listed:
   - ✅ Maps JavaScript API
   - ✅ Places API

---

## Create API Key

### Step 1: Navigate to Credentials

1. Click hamburger menu (☰) → **APIs & Services** → **Credentials**
2. Or visit: https://console.cloud.google.com/apis/credentials

### Step 2: Create New API Key

1. Click **+ Create Credentials** at the top
2. Select **API key**
3. API key will be generated automatically
4. Copy the API key immediately (format: `AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`)
5. **DO NOT CLOSE** the popup - continue to restrictions

---

## Configure API Key Restrictions

### Application Restrictions

1. In the API key popup or credentials page, find **Application restrictions**
2. Select **HTTP referrers (websites)**
3. Click **+ Add an item** under "Website restrictions"
4. Add your WordPress site domains:

```
https://yourdomain.com/*
https://www.yourdomain.com/*
http://localhost/*
http://127.0.0.1/*
```

**Examples:**
```
https://myeventsite.com/*
https://www.myeventsite.com/*
https://staging.myeventsite.com/*
http://localhost/*
```

**Important Notes:**
- Replace `yourdomain.com` with your actual domain
- Include both `www` and non-www versions
- Add `http://localhost/*` for local development
- The `/*` wildcard allows all paths on the domain

### API Restrictions

1. Scroll down to **API restrictions**
2. Select **Restrict key**
3. Click the dropdown and select:
   - ✅ Maps JavaScript API
   - ✅ Places API
4. Click **OK**
5. Click **Save** at the bottom

### Copy the API Key

1. Click the copy icon next to your API key
2. Store it securely (you'll need it for the plugin configuration)

**Example API Key Format:**
```
AIzaSyDZU1iNQDWeXWw-m5YQqZLrIb8ghMgc_j4
```

---

## Update Plugin Configuration

### Method 1: Update config.js (Recommended)

1. Navigate to plugin directory:
   ```
   eventbookings/includes/js/
   ```

2. Open `config.js` in a text editor

3. Locate line 7:
   ```javascript
   static GOOGLE_MAP_API_KEY = 'AIzaSyDZU1iNQDWeXWw-m5YQqZLrIb8ghMgc_j4';
   ```

4. Replace with your new API key:
   ```javascript
   static GOOGLE_MAP_API_KEY = 'YOUR_NEW_API_KEY_HERE';
   ```

5. Save the file

### Method 2: Rebuild JavaScript Bundle

After updating `config.js`, rebuild the component bundle:

```bash
# Navigate to JavaScript directory
cd eventbookings/includes/js/

# Install dependencies (if not already installed)
npm install

# Build the bundle
npm run build
```

**Output:**
```
dist/component-bundle.js (updated with new API key)
```

### Method 3: Clear WordPress Cache

If using caching plugins:

1. Go to WordPress Admin → Plugins
2. Find your caching plugin (WP Super Cache, W3 Total Cache, etc.)
3. Click "Clear Cache" or "Purge Cache"
4. Or deactivate/reactivate the EventBookings plugin

---

## Testing & Verification

### Step 1: Test on Event Details Page

1. Navigate to a WordPress page with event details
2. Scroll to "Find The Venue On Map" section
3. Verify the map displays without watermark

### Step 2: Check Browser Console

1. Open browser Developer Tools (F12)
2. Go to **Console** tab
3. Look for messages:
   - ✅ `"Google Maps API loaded"`
   - ✅ `"Initializing Google Map"`
   - ❌ No error messages about API key restrictions

### Step 3: Verify Map Functionality

Confirm the following works:
- ✅ Map loads without "For development purposes only" watermark
- ✅ Location marker appears at event venue
- ✅ Zoom controls functional (+ and - buttons)
- ✅ Pan/drag functionality works
- ✅ "View on Map" link opens Google Maps in new tab

### Step 4: Test Multiple Events

1. Test with different events (different locations)
2. Verify each event's venue location displays correctly
3. Confirm latitude/longitude data from API renders properly

---

## Troubleshooting

### Issue 1: "For development purposes only" Watermark Still Appears

**Cause:** API key restrictions don't match your domain

**Solutions:**
1. **Check HTTP Referrer Restrictions:**
   - Go to Google Cloud Console → Credentials
   - Click your API key
   - Verify your WordPress domain is listed in referrers
   - Ensure you included the `/*` wildcard
   - Example: `https://yourdomain.com/*`

2. **Wait for Propagation:**
   - Changes can take 5-10 minutes to propagate
   - Clear browser cache and try again

3. **Temporarily Remove Restrictions (Testing Only):**
   - Set Application restrictions to "None"
   - Test if watermark disappears
   - If it works, the issue was referrer restrictions
   - Re-add restrictions with correct domain

### Issue 2: Map Not Loading at All

**Cause:** APIs not enabled or billing not configured

**Solutions:**
1. **Verify APIs are Enabled:**
   - Console → APIs & Services → Enabled APIs
   - Confirm Maps JavaScript API and Places API are listed

2. **Check Billing Status:**
   - Console → Billing
   - Ensure billing account is linked and active

3. **Check Browser Console for Errors:**
   - Open Developer Tools (F12) → Console
   - Look for specific error messages
   - Common errors:
     - `"Google Maps JavaScript API error: ApiNotActivatedMapError"`
       → Enable Maps JavaScript API
     - `"Google Maps JavaScript API error: RefererNotAllowedMapError"`
       → Fix HTTP referrer restrictions
     - `"Google Maps JavaScript API error: BillingNotEnabledMapError"`
       → Enable billing on project

### Issue 3: Map Shows Grey Box with No Content

**Cause:** Invalid coordinates or venue data missing

**Solutions:**
1. **Check Event Data:**
   - Open browser console
   - Type: `console.log(window.eventDetails)`
   - Verify venue object has latitude/longitude

2. **Check API Response:**
   - Ensure EventBookings API returns venue data
   - Verify event configuration type is "VENUE" not "ONLINE"

3. **Check Config:**
   - File: `EventDetails.js` line 269-271
   - Ensure map initialization is not blocked

### Issue 4: "This page can't load Google Maps correctly"

**Cause:** API key invalid or quota exceeded

**Solutions:**
1. **Verify API Key is Correct:**
   - Check `config.js` has the correct key
   - Ensure no extra spaces or characters

2. **Check API Key Status:**
   - Console → Credentials
   - Verify API key is not disabled or deleted

3. **Check Quota:**
   - Console → APIs & Services → Dashboard
   - Click Maps JavaScript API
   - View quotas and usage
   - Ensure you haven't exceeded free tier limits

### Issue 5: Map Loads but Marker Missing

**Cause:** Marker icon path incorrect

**Solutions:**
1. **Check Marker Icon Path:**
   - File: `EventDetails.js` line 502
   - Current: `markerIcon: '/site/images/location_marker.png'`
   - Verify this path exists on your WordPress site
   - Or set to `null` to use default Google marker

2. **Use Default Marker:**
   ```javascript
   $('#map').locationpicker({
       location: {latitude, longitude},
       markerIcon: null, // Use default Google marker
       // ... other options
   });
   ```

### Issue 6: Changes Not Reflecting After Update

**Cause:** JavaScript bundle not rebuilt or cache issue

**Solutions:**
1. **Rebuild JavaScript Bundle:**
   ```bash
   cd eventbookings/includes/js/
   npm run build
   ```

2. **Clear Browser Cache:**
   - Chrome: Ctrl+Shift+Delete → Clear browsing data
   - Or use hard reload: Ctrl+Shift+R

3. **Clear WordPress Cache:**
   - WP Admin → Clear all caches
   - Or deactivate caching plugin temporarily

4. **Check File Timestamps:**
   - Verify `dist/component-bundle.js` timestamp is recent
   - If old, rebuild didn't work properly

### Issue 7: API Key Exposed in Source Code

**Security Concern:** API key visible in browser source

**This is Normal for Client-Side Maps:**
- Google Maps JavaScript API requires client-side keys
- Security is managed through HTTP referrer restrictions
- Properly restricted keys cannot be abused from other domains

**Best Practices:**
1. ✅ Always set HTTP referrer restrictions
2. ✅ Enable only required APIs (Maps JavaScript, Places)
3. ✅ Monitor usage in Google Cloud Console
4. ✅ Set up budget alerts to prevent unexpected charges
5. ❌ Never use server-side API keys client-side

### Issue 8: Multiple Maps on Same Page

**Issue:** Only one map loads when multiple events displayed

**Solution:**
- Current code initializes one map with ID `#map`
- For multiple maps, unique IDs needed per event
- Requires code modification (not covered in config)

---

## Configuration Checklist

Use this checklist to verify complete setup:

### Google Cloud Console
- [ ] Google Cloud project created
- [ ] Billing enabled on project
- [ ] Maps JavaScript API enabled
- [ ] Places API enabled
- [ ] API key created
- [ ] HTTP referrer restrictions configured
- [ ] API restrictions set (Maps JavaScript + Places)
- [ ] API key copied and saved

### Plugin Configuration
- [ ] `config.js` updated with new API key
- [ ] JavaScript bundle rebuilt (`npm run build`)
- [ ] WordPress cache cleared
- [ ] Browser cache cleared

### Testing
- [ ] Map loads without watermark
- [ ] Location marker appears
- [ ] Zoom controls work
- [ ] No console errors
- [ ] Multiple events tested
- [ ] Mobile view tested

---

## Support Resources

### Google Cloud Documentation
- Maps JavaScript API: https://developers.google.com/maps/documentation/javascript
- Places API: https://developers.google.com/maps/documentation/places/web-service
- API Key Best Practices: https://developers.google.com/maps/api-security-best-practices

### Plugin Documentation
- Main plugin file: `eventbookings/eventbookings.php`
- Map component: `eventbookings/includes/js/src/component/event-details/EventDetails.js`
- Helper functions: `eventbookings/includes/js/src/utils/helpers.js`
- Configuration: `eventbookings/includes/js/config.js`

### Quick Reference

**Current API Key (Example):**
```
AIzaSyDZU1iNQDWeXWw-m5YQqZLrIb8ghMgc_j4
```

**Config File Location:**
```
eventbookings/includes/js/config.js (line 7)
```

**Rebuild Command:**
```bash
cd eventbookings/includes/js/ && npm run build
```

**Map Container HTML ID:**
```html
<div id="map" class="eb-map-render-wrap"></div>
```

---

## Monthly Cost Estimates

Google Maps Pricing (after free $200 credit):

| Usage Level | Map Loads/Month | Cost After Credit |
|-------------|-----------------|-------------------|
| Small Site  | 1,000 - 10,000  | $0 (covered by free tier) |
| Medium Site | 10,000 - 28,000 | $0 (covered by free tier) |
| Large Site  | 50,000          | ~$56/month |
| Very Large  | 100,000         | ~$256/month |

**Notes:**
- First $200/month usage is free
- $7 per 1,000 map loads after free tier
- Places API (autocomplete) charged separately if used
- Monitor usage in Console to avoid surprises

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-01-09 | Initial configuration guide |

---

**Last Updated:** January 9, 2025
**Plugin Version:** 1.3
**Tested With:** WordPress 6.4+, EventBookings API v3