Analytics & Dashboards - Macondo Link Manager

Overview

Macondo Link Manager provides powerful analytics to track link performance across your organization. View metrics at multiple levels - from individual links to entire clients - with automatic bot detection to ensure data accuracy.

Multi-Level Views

Analytics for links, campaigns, clients, or entire agency

Bot Filtering

Intelligent bot detection excludes fake traffic

Geographic Data

Track clicks by country and city

Time-Based Analysis

Filter by custom date ranges

Dashboard Types

The analytics system provides four distinct dashboard views:

1. General Overview

Agency-wide metrics across all links for the authenticated user.

GET /dashboard/overview

Shows:

Total clicks across all links
Number of active links
Click trends over time (last 30 days)
Top browsers, countries, and cities

2. Client Dashboard

Metrics for all links associated with a specific client.

GET /dashboard/clients/:clientId/overview

Shows:

Client-specific click totals
Active links for this client
Performance trends
Geographic and browser breakdowns

3. Campaign Dashboard

Analytics for links within a specific campaign.

GET /dashboard/campaigns/:campaignId/overview

Shows:

Campaign-specific metrics
Links in this campaign
Campaign performance trends
Detailed click analytics

Campaign dashboards verify that the authenticated user has links in the campaign before showing data. This prevents unauthorized access to campaign analytics.

4. Link Metrics

Detailed analytics for an individual link.

GET /links/:id/metrics?days=30

Shows:

Click history by date
Browser distribution
Geographic breakdown
Configurable time range (1-365 days)

Metrics Tracked

Click Data

Every click on a shortened link records:

timestamp

datetime

When the click occurred (UTC)

ipAddress

string | null

IP address of the visitor (if available)

userAgent

string | null

Browser and device information

country

string | null

Country derived from IP geolocation

city

string | null

City derived from IP geolocation

isBot

boolean

Whether this click was identified as bot traffic

botReason

string | null

Explanation for why click was flagged as bot

Click Recording Process

Link accessed

User clicks on shortened link

Data collection

System captures IP, user agent, and request headers

Bot detection

Traffic is analyzed using multiple detection methods

Geolocation lookup

IP address is resolved to country and city (only for non-bot traffic)

Database recording

Click data is stored with bot flag and reason

Redirection

User is redirected to the original URL

Bot Filtering Mechanism

The system employs sophisticated bot detection to maintain analytics accuracy.

Detection Methods

User Agent Analysis

Identifies known bot patterns in browser strings

Request Headers

Examines HTTP headers for bot signatures

Burst Detection

Flags rapid repeated clicks from same source

ASN Organization

Checks if IP belongs to known hosting/datacenter networks

Bot Detection Implementation

const { isBot, reason } = detectBot(userAgent, headers, {
  burst,
  asnOrg: asnInfo?.organization ?? null,
});

Common Bot Reasons

Reason	Description
`user-agent-bot`	User agent string indicates a bot
`click-burst`	Too many clicks in short time period
`datacenter-ip`	IP belongs to hosting/datacenter ASN
`missing-headers`	Expected browser headers absent
`automation-tools`	Signature of automation software detected

Bot traffic is recorded but excluded from analytics. While bot clicks are stored in the database with isBot: true, they don’t appear in dashboard metrics or link analytics.

Geographic Data for Bots

To optimize performance:

Bot traffic: Geolocation lookup is skipped; country and city are null
Human traffic: Full geolocation is performed

This reduces unnecessary API calls and database load.

Dashboard Response Structure

All overview endpoints return data in this format:

{
  "summary": {
    "totalClicks": 12847,
    "activeLinks": 243,
    "period": "last 30 days"
  },
  "charts": {
    "clicksByDate": [
      { "date": "2024-03-01", "count": 423 },
      { "date": "2024-03-02", "count": 456 },
      { "date": "2024-03-03", "count": 389 }
    ],
    "topBrowsers": [
      { "browser": "Chrome", "count": 7234 },
      { "browser": "Safari", "count": 3456 },
      { "browser": "Firefox", "count": 1234 },
      { "browser": "Edge", "count": 923 }
    ],
    "topCountries": [
      { "country": "Brazil", "count": 5678 },
      { "country": "Uruguay", "count": 3456 },
      { "country": "Argentina", "count": 2345 },
      { "country": null, "count": 1368 }
    ],
    "topCities": [
      { "city": "São Paulo", "count": 2890 },
      { "city": "Montevideo", "count": 2345 },
      { "city": "Buenos Aires", "count": 1567 },
      { "city": null, "count": 1234 }
    ]
  },
  "meta": {
    "hasData": true
  }
}

Summary Metrics

totalClicks

number

Total number of legitimate (non-bot) clicks in the period

activeLinks

number

Number of links with at least one click in the period

period

string

Human-readable description of the time range

Chart Data

clicksByDate

array

Daily click counts for trend visualization

topBrowsers

array

Most common browsers ordered by click count

topCountries

array

Geographic distribution by country

topCities

array

Geographic distribution by city

Entries with null for country or city represent clicks where geolocation data couldn’t be determined (typically VPNs or privacy-focused browsers).

Top Clients Ranking

View which clients are generating the most traffic.

API Endpoint

GET /dashboard/top-clients

Response

[
  { "name": "Acme Corporation", "clicks": 45678 },
  { "name": "Tech Startup Inc", "clicks": 23456 },
  { "name": "Fashion Brand Co", "clicks": 12345 },
  { "name": "Restaurant Chain", "clicks": 8901 },
  { "name": "E-commerce Shop", "clicks": 5678 }
]

Returns: Top 5 clients by total click count for the authenticated user.

Use this data to identify your highest-performing clients and allocate resources accordingly.

Time-Based Filtering

Link metrics support custom time ranges for flexible analysis.

API Endpoint

GET /links/:id/metrics?days=90

Parameters

days

number

default:"30"

Number of days to include in metricsRange: 1-365 days

Example Queries

curl "https://api.macondo.link/links/{id}/metrics?days=7" \
  -H "Cookie: macondo.token=YOUR_TOKEN"

Browser Analytics

Understand which browsers your audience uses.

Browser Detection

Browser information is extracted from the User-Agent string:

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
  ↓
Browser: Chrome

Common Browsers Tracked

Chrome
Safari
Firefox
Edge
Opera
Samsung Internet
Mobile browsers (iOS Safari, Chrome Mobile)

Browser detection is performed server-side during click recording and stored for efficient querying.

Geographic Analytics

Track where your traffic originates.

Geolocation Process

IP capture

Visitor’s IP address is captured from the request

Bot check

If traffic is flagged as bot, skip geolocation

GeoIP lookup

IP is resolved to country and city using GeoIP database

Data storage

Geographic information is stored with the click

Implementation

if (!isBot && ipAddress) {
  const geo = await resolveGeoLocation(ipAddress);
  country = geo?.country;
  city = geo?.city;
}

Geographic Data Limitations

VPNs

May report VPN server location, not user’s actual location

Privacy Browsers

Some browsers mask IP addresses

Corporate Networks

May show headquarters location for distributed teams

Mobile Networks

City accuracy varies by carrier

Campaign Analytics Authorization

Campaign dashboards include access control.

Authorization Check

Before showing campaign analytics, the system verifies:

Campaign exists: The campaign ID is valid
User has links: The user has at least one link in this campaign

Error Response

If unauthorized:

{
  "message": "Você não tem permissão para acessar esta campanha."
}

HTTP Status: 403 Forbidden

This prevents users from viewing analytics for campaigns they’re not involved with, even though clients and campaigns are globally visible.

Data Retention

Click data is retained indefinitely by default.

What’s Stored

Every individual click record
All associated metadata (timestamp, IP, geolocation, etc.)
Bot classification and reason

Cascade Deletion

Click data is automatically deleted when:

Link deleted: All clicks for that link are removed
Client deleted: All clicks for links under that client are removed
User deleted: All clicks for links created by that user are removed

When you delete a link, client, or campaign, the associated analytics data is permanently lost. Consider exporting reports before deletion if you need to preserve historical data.

Performance Optimization

Database Indexes

The clicks table includes indexes for fast querying:

INDEX idx_clicks_link_id ON clicks(link_id)
INDEX idx_clicks_timestamp ON clicks(timestamp)

These ensure quick aggregation even with millions of clicks.

Bot Traffic Exclusion

By filtering bots at the query level, analytics remain fast:

SELECT COUNT(*) 
FROM clicks 
WHERE link_id = ? 
  AND is_bot = false
  AND timestamp >= ?

Analytics API Summary

Endpoint	Scope	Description
`GET /dashboard/overview`	Agency	All user’s links (30 days)
`GET /dashboard/clients/:id/overview`	Client	All links for a client
`GET /dashboard/campaigns/:id/overview`	Campaign	All links in a campaign
`GET /dashboard/top-clients`	Agency	Top 5 clients by clicks
`GET /links/:id/metrics?days=N`	Link	Single link (custom range)

Visualization Recommendations

Click Trends

Best visualized as:

Line chart: Show click trends over time
Area chart: Emphasize volume changes
Bar chart: Compare discrete time periods

Browser Distribution

Best visualized as:

Pie chart: Show proportional breakdown
Horizontal bar chart: Rank browsers by usage
Donut chart: Clean percentage view

Geographic Data

Best visualized as:

Map view: Plot countries with heat intensity
Table: List countries/cities with click counts
Bar chart: Compare top locations

Aggregate Metrics

Best visualized as:

Stat cards: Highlight key numbers (total clicks, active links)
Comparison cards: Show period-over-period changes
Gauge charts: Display progress toward goals

Best Practices

Monitor Bot Rates

Regularly check the ratio of bot to human traffic to identify attacks

Compare Time Periods

Use custom date ranges to identify trends and seasonality

Geographic Insights

Use location data to optimize campaign timing and targeting

Browser Compatibility

Ensure your destination pages work well on top browsers

Set up regular reporting by exporting dashboard data weekly or monthly. This helps identify long-term trends that may not be visible in real-time monitoring.

Get Started

Core Features

Guides

​Overview

Multi-Level Views

Bot Filtering

Geographic Data

Time-Based Analysis

​Dashboard Types

​1. General Overview

​2. Client Dashboard

​3. Campaign Dashboard

​4. Link Metrics

​Metrics Tracked

​Click Data

​Click Recording Process

​Bot Filtering Mechanism

​Detection Methods

User Agent Analysis

Request Headers

Burst Detection

ASN Organization

​Bot Detection Implementation

​Common Bot Reasons

​Geographic Data for Bots

​Dashboard Response Structure

​Summary Metrics

​Chart Data

​Top Clients Ranking

​API Endpoint

​Response

​Time-Based Filtering

​API Endpoint

​Parameters

​Example Queries

​Browser Analytics

​Browser Detection

​Common Browsers Tracked

​Geographic Analytics

​Geolocation Process

​Implementation

​Geographic Data Limitations

VPNs

Privacy Browsers

Corporate Networks

Mobile Networks

​Campaign Analytics Authorization

​Authorization Check

​Error Response

​Data Retention

​What’s Stored

​Cascade Deletion

​Performance Optimization

​Database Indexes

​Bot Traffic Exclusion

​Analytics API Summary

​Visualization Recommendations

​Click Trends

​Browser Distribution

​Geographic Data

​Aggregate Metrics

​Best Practices

Monitor Bot Rates

Compare Time Periods

Geographic Insights

Browser Compatibility

Build docs developers (and LLMs) love

Overview

Dashboard Types

1. General Overview

2. Client Dashboard

3. Campaign Dashboard

4. Link Metrics

Metrics Tracked

Click Data

Click Recording Process

Bot Filtering Mechanism

Detection Methods

Bot Detection Implementation

Common Bot Reasons

Geographic Data for Bots

Dashboard Response Structure

Summary Metrics

Chart Data

Top Clients Ranking

API Endpoint

Response

Time-Based Filtering

API Endpoint

Parameters

Example Queries

Browser Analytics

Browser Detection

Common Browsers Tracked

Geographic Analytics

Geolocation Process

Implementation

Geographic Data Limitations

Campaign Analytics Authorization

Authorization Check

Error Response

Data Retention

What’s Stored

Cascade Deletion

Performance Optimization

Database Indexes

Bot Traffic Exclusion

Analytics API Summary

Visualization Recommendations

Click Trends

Browser Distribution

Geographic Data

Aggregate Metrics

Best Practices