MapFlow Pro - Complete Setup Guide

🚀

What's New in V2?

✅ 100% Backward Compatible

Your existing V1 setup will continue to work perfectly. These V2 features are optional additions you can enable at any time.

New Customization Features

🎨 Dynamic Colors: Automatically color markers based on your data.
📝 Tooltip Templates: Fully customize tooltips using a simple `{{field}}` syntax.
📍 Custom SVG Icons: Choose between Pin, Circle, and Square marker shapes, or use a dynamic image URL.
✨ Dynamic Tooltip Themes: Change tooltip colors based on your data.

V2 Features in Action

Click the links below to see screenshots of the new features and their configuration.

V2 Feature	Configuration	Live Preview
Dynamic Colors	📸 View Config	🗺️ View Map
Tooltip Templates	📸 View Config	💬 View Tooltip
Custom Icons (Shapes)	📸 View Config	📍 View Icons
Tooltip Themes	📸 View Config	🎨 View Themes

📦

Installation & Initial Setup

Step 1: Install MapFlow Pro Plugin

📸 Screenshot: MapFlow Pro installation from Bubble marketplace 👆 Click to view

Go to your Bubble app editor
Navigate to Plugins tab
Click "Add plugins"
Search for "MapFlow Pro"
Click "Install" and accept the plugin

Step 2: Get HERE Maps API Key

📸 Screenshot: HERE API key generation process 👆 Click to view

Visit developer.here.com
Create a FREE HERE developer account
Create a new project
Generate an API key
Copy the API key for Bubble configuration

💡 HERE Free Tier

HERE provides 250,000 free requests per month, which covers most applications. No credit card required for the free tier.

Step 3: Configure Privacy Rules

📸 Screenshot: Privacy rules configuration for user geolocation 👆 Click to view

⚠️ Critical: Privacy Rules Setup

If your map doesn't load or shows no data, privacy rules are often the cause. Ensure your data types have proper privacy rules configured:

Allow "Everyone" to view location fields (lat, lng) if using public data
Or configure specific privacy rules for your user type
Check that geographic address fields are accessible

🏗️

Critical Layout Configuration

Essential Layout Requirements

📸 Screenshot: Correct layout configuration - Column group with fixed height 👆 Click to view

🚨 Layout Critical Issue

The map will NOT load properly if not placed in a Column group with fixed height. This is the most common configuration error.

Correct Layout Structure

                        Page Layout
                        └── Column Group (container for map)
                        ├── Make this element fixed-height: ON
                        ├── Min height: 600-800px
                        ├── Fit height to content: OFF
                        ├── Make this element fixed-width: OFF
                        └── MapFlow Element (inside this column)
                    

Layout Settings Checklist

Container Group: Use Column (not Row) for the map container
Fixed Height: Enable "Make this element fixed-height"
Minimum Height: Set to at least 600px (800px recommended)
Fit Height to Content: Must be OFF
Width: Keep "Make this element fixed-width" OFF for responsive design

💡 Layout Best Practice

Other page sections (headers, navigation, footers) can use Row layout, but the map container must always be a Column with fixed height.

⏱️

Critical Workflow Timing

🚨 Mandatory 1000ms Pause

ALWAYS add a 1000ms pause between draw_route and compute_fare actions. This ensures the route calculation completes before fare calculation begins. Without this pause, fare calculation will fail or return incorrect values.

Correct Workflow Sequence

                        // Workflow: Calculate Route and Fare
                        1. Action: draw_route
                        - origin_lat: Input From's latitude
                        - dest_lat: Input To's latitude
                        - mode: "car"

                        2. Action: Pause
                        - Duration: 1000ms

                        3. Action: compute_fare
                        - base_fee: 3.50
                        - per_km: 1.45
                        - surge_multiplier: 1.0
                    

📸 Screenshot: Draw route workflow configuration 👆 Click to view

💡 Alternative: Use Events

Instead of a fixed pause, you can use the route_ready event to trigger the compute_fare action. This ensures perfect timing regardless of network conditions.

⚙️

MapFlow Element Configuration

Basic Configuration

📸 Screenshot: MapFlow element configuration panel 👆 Click to view

Required Fields

Field	Type	Required	Description
marker_data_source	Dynamic Value	Yes	Your data source (list of things)
lat_key	Static text	Yes	Field name for latitude (e.g., "lat", "latitude")
lng_key	Static text	Yes	Field name for longitude (e.g., "lng", "longitude")
name_key	Static text	Optional	Field name for marker title

🔧

Troubleshooting Common Issues

Map Not Loading

❌ Issue: Map appears blank or doesn't load

Most Common Causes:

Layout Issue: Map not in a Column group with fixed height
Privacy Rules: Data fields not accessible due to privacy settings
Invalid API Key: HERE API key missing or incorrect
Data Source: Empty or malformed data source

Solutions:

Check layout configuration (Column + fixed height)
Verify privacy rules allow access to lat/lng fields
Test HERE API key in HERE developer console
Ensure data source contains valid latitude/longitude values

❌ Issue: Workflow timing problems

Common Causes:

compute_fare called before route completion
Missing 1000ms pause between actions
Network latency causing timing issues