Map Block: Mapbox & Google Maps Integration

Integrate an interactive map by selecting either Mapbox or Google Maps in the Map Block settings.

1. Choose a Provider

Mapbox is often more cost‑effective; Google Maps provides familiar styling. Direction links always open in Google Maps for consistency.

2. Setup Guides

Mapbox Setup

2.1 Create an Access Token

1. Open: Mapbox Access Tokens
2. Name it (e.g. “Storefront Map Block”).
3. Scopes: leave defaults (public scopes are enough).
4. URL Restrictions (SECURITY):
   • Add every domain that will load the map (Shopify + custom + staging).
   • Examples:
     • https://your-store.myshopify.com
     • https://www.yourcustomdomain.com
     • https://staging.yourcustomdomain.com
   • Avoid trailing paths unless needed. Wildcards allowed.
5. Save & copy the token (store securely).

2.2 Add Token in Theme Editor

1. Theme Editor → Map Block settings
2. Provider: Mapbox
3. Paste token in “Mapbox Access Token”
4. Save & preview

2.3 Troubleshooting

Issue	Likely Cause	Fix
Blank / gray tiles	Missing or invalid token	Re‑paste token; remove spaces.
401 errors	Domain not in restriction list	Add domain & wait a few minutes.
Mixed content warning	http used on https site	Use only https URLs.

Google Maps Setup

2.1 Create an API Key

1. Open: Google Cloud Maps Credentials
2. Create Credentials → API key.
3. Copy the generated key.
4. Open the key details to secure it.

2.2 Secure the Key

1. Name it clearly.
2. Application restrictions: “Web sites”.
3. Add every production + staging domain (protocol included).
4. API restrictions: allow only “Maps JavaScript API” (+ Geocoding API if address lookup needed).
5. Save.

2.3 Add Key in Theme Editor

1. Theme Editor → Map Block settings
2. Provider: Google Maps
3. Paste key in “Google Maps API Key”
4. Save & hard refresh

2.4 Troubleshooting

Issue	Likely Cause	Fix
“For development purposes only”	Billing inactive / APIs disabled	Enable billing + required APIs.
RefererNotAllowedMapError	Missing or mismatched referrer	Add exact domain (with protocol).
OVER_QUERY_LIMIT	Exceeded quota	Increase quota or reduce requests.
Blank map	CSP or blocked script	Check console & CSP headers.

3. Domain Guidelines (Both Providers)

Include every domain:

• Shopify default: https://your-store.myshopify.com
• Primary custom: https://www.example.com (and apex https://example.com)
• Staging / preview: https://preview.example.com

4. Security Best Practices

• Use only public (client‑side safe) keys / tokens
• Enforce domain (referrer) restrictions
• Rotate if suspicious activity detected

5. Switching Providers

Remove or leave blank the unused provider key; only the selected provider loads.