Overview
What is Heatmap Ad Integration?
The Heatmap Ad Integration feature allows you to track and analyze user behavior from specific advertising campaigns. It connects your ad platforms (Facebook, Google, TikTok, X/Twitter) with your heatmap data, enabling you to see exactly how visitors from each ad campaign interact with your website.
Which ad platforms are supported?
Currently supported platforms include:
Facebook (including Facebook Ads)
Google (Google Ads)
TikTok (TikTok Ads)
X/Twitter (Twitter Ads)
Klaviyo
How does it work?
When users click on your ads, they're directed to your website with UTM parameters that identify the ad source. Our system tracks all their interactions (clicks, scrolls, page navigation) and allows you to filter this data by specific ad campaigns.
Getting Started
How do I connect my ad platforms?
There are two ways to connect your ad platforms:
Method 1: Through Settings
Navigate to Settings > Integrations
Click "Connect" next to your desired platform
A pop-up will appear for account authorization
Select your account and click "Continue"
The platform will show as "Connected"
Method 2: Through Heatmap Filters
Go to your Heatmap dashboard
Click on "Filters"
Select "AD Platform" filter
Click "Connect" for your desired platform
Complete the authorization process
Do I need special permissions for my ad accounts?
Yes, you'll need admin or appropriate permissions on your ad accounts to authorize the connection. Each platform has its own requirements:
Facebook: Admin access to ad accounts
Google: Manager access to Google Ads
TikTok: Advertiser account access
X/Twitter: Premium verification may be required for ads
What happens after I connect a platform?
Once connected, the system will:
Fetch all your ad accounts for that platform
Display available campaigns
Begin tracking sessions from those campaigns
Enable filtering options in your heatmap dashboard
Using the Feature
How do I view heatmap data for specific ad campaigns?
Go to your Heatmap dashboard
Click the "Filters" button
Select "Ads Platform" from the filter options
Choose your connected platform
Select specific campaigns you want to analyze
The heatmap will update to show only sessions from those campaigns
Can I filter by multiple campaigns?
Yes, you can select multiple campaigns from the same platform or even across different platforms to compare performance.
What metrics can I see?
The integration provides:
Number of sessions per campaign
Device breakdown (desktop/mobile/tablet)
User interactions (clicks, scrolls, time on page)
Navigation paths through your site
Conversion tracking (if configured)
How do I disconnect a platform?
Go to Settings > Integrations
Find the connected platform
Click the "Disconnect" button
Confirm the disconnection
Note: Disconnecting will not delete historical data but will stop tracking new sessions from that platform.
Tracking and Analytics
How are sessions tracked from ads?
Sessions are tracked using UTM parameters automatically added to your ad URLs. These parameters include:
utm_source (platform name)
utm_medium (ad type)
utm_campaign (campaign name)
utm_content (ad creative identifier)
Platform-specific parameters (fbclid, gclid, ttclid)
ad_id ( the ad identifier )
adset_id ( the adset or adgroup identifier )
campaign_id ( the campaign Identifier )
Why don't I see any data after connecting?
Several reasons might cause this:
No active campaigns: Ensure you have running campaigns with traffic
Recent connection: It may take up to 30 minutes for initial data to appear
UTM parameters: Verify your ads include proper tracking parameters
Ad approval: Some platforms require ad approval before they go live
Tracking script: Ensure your heatmap tracking script is properly installed
Can I see historical data from before I connected?
No, the integration only tracks sessions from the moment you connect your ad platform. Historical ad performance data is not retroactively added.
How accurate is the tracking?
Tracking accuracy depends on:
Proper UTM parameter implementation
Users not using ad blockers
Correct heatmap script installation
Cookie acceptance by users
Troubleshooting
My platform shows as connected but I see no campaigns
This could happen if:
You have no active campaigns in that ad account
The account permissions are insufficient
There's a sync delay (wait 15-30 minutes)
Try disconnecting and reconnecting the platform
Sessions aren't appearing in the filter
Check the following:
Verify ads are actively running and receiving clicks
Confirm UTM parameters are present in your ad URLs
Check that the heatmap tracking script is on all pages
Ensure cookies are enabled for tracking
Wait at least 30 minutes after generating test traffic
I'm getting an authentication error
Your ad platform session may have expired
Platform permissions may have changed
Try disconnecting and reconnecting the platform
Ensure you're using the correct account credentials
Filter shows zero sessions but I know there's traffic
Double-check campaign selection in the filter
Verify date range includes when ads were running
Confirm UTM parameters match expected values
Clear browser cache and refresh the dashboard
Best Practices
Setting up campaigns for optimal tracking
Always use consistent UTM naming conventions
Test tracking with a small budget first
Create separate campaigns for different objectives
Use descriptive campaign names for easy filtering
Analyzing the data
Compare heatmaps between campaigns to identify best performers
Look for patterns in user behavior by device type
Use session recordings alongside heatmaps for deeper insights
Export data regularly for historical analysis
Privacy and compliance
Ensure you have proper consent for tracking users
Include privacy policy updates mentioning ad tracking
Comply with platform-specific privacy requirements
Respect user opt-outs and do-not-track settings
Limitations
What are the current limitations?
Real-time data may have a 15-30 minute delay
Maximum of 10,000 sessions per filter view
Some ad platforms require premium accounts
Cross-domain tracking requires additional setup
Platform-specific limitations
X/Twitter: Requires premium verification for ads
Google: Ads API requires separate approval process
Facebook: Limited to accounts you admin
TikTok: Business account required
Getting Help
Where can I get additional support?
If you need further assistance:
Contact our support team through the help center
Check our video tutorials for visual guides
Join our community forum for tips from other users
Schedule a demo with our success team for advanced features
How do I report a bug or request a feature?
Use the feedback button in the dashboard
Email our product team directly
Submit detailed reports including screenshots
Include steps to reproduce any issues
Questions? Reach out to support@heatmap.com - we're here to help you succeed.