UTM Link Shortener

A comprehensive Frappe app for UTM parameter generation and URL shortening with advanced analytics.

🚀 Features

🔗 URL Shortening

• Generate short, memorable URLs
• Custom aliases support
• Bulk URL creation
• Expiration date management
• Domain blocking for security

📊 UTM Parameter Management

• Complete UTM parameter builder
• Template system for reusable campaigns
• Automatic URL generation with UTM parameters
• Auto-computed full URLs with UTM parameters
• Campaign code generation
• One-click URL copying to clipboard

📈 Advanced Analytics

• Real-time click tracking
• Device type detection (Desktop/Mobile/Tablet)
• Browser and OS identification
• Geolocation tracking (optional)
• Country-wise analytics
• Unique visitor counting

🛡️ Security Features

• Rate limiting
• Domain blocking
• URL validation
• Malicious URL detection
• Permission-based access control

🔧 Installation

Prerequisites

• Frappe Framework v15+
• ERPNext v15+ (optional but recommended)

Setup

1. Clone this repository to your Frappe bench apps folder:

cd frappe-bench/apps
git clone https://github.com/chinmaybhatk/utm_shortener.git

2. Install the app to your site:

bench --site your-site.local install-app utm_shortener

3. Run database migrations:

bench --site your-site.local migrate

4. Create the required DocTypes manually:

   • UTM Campaign
   • Short URL
   • URL Click Log
   • UTM Template
   • UTM Shortener Settings (Single DocType)

5. Configure settings:

   • Go to UTM Shortener Settings
   • Set your base domain
   • Configure rate limits
   • Enable geolocation if needed

📚 Quick Start

Creating a UTM Campaign with Auto-Generated URLs

1. Navigate to UTM Campaign in the desk
2. Click New
3. Fill in campaign details:
   • Campaign Name: "Summer Sale 2025"
   • UTM Source: "email"
   • UTM Medium: "newsletter"
   • UTM Campaign: "summer_sale_2025"
   • Base URL: "https://example.com/products" (NEW)
4. The Full URL with UTM Parameters will be automatically generated
5. Click Copy Full URL button to copy the complete URL
6. Save

Creating Short URLs

1. Go to Short URL in the desk
2. Click New
3. Enter your original URL
4. Select a UTM Campaign (optional)
5. Add custom alias (optional)
6. Save

🔌 API Usage

Create Short URL

import requests

response = requests.post('https://yoursite.com/api/method/utm_shortener.utm_shortener.api.create_short_url', {
    'original_url': 'https://example.com/product',
    'utm_campaign': 'summer_sale_campaign',
    'custom_alias': 'summer-sale'
})

data = response.json()
print(data['message']['short_url'])

Generate UTM URL

response = requests.post('https://yoursite.com/api/method/utm_shortener.utm_shortener.doctype.utm_campaign.utm_campaign.generate_utm_url', {
    'campaign_name': 'CAMP-001',
    'base_url': 'https://example.com/products'
})

utm_url = response.json()['message']
print(f"Generated URL: {utm_url}")

Get Analytics

response = requests.get('https://yoursite.com/api/method/utm_shortener.utm_shortener.api.get_url_analytics', {
    'short_code': 'abc123'
})

analytics = response.json()['message']
print(f"Total clicks: {analytics['short_url']['total_clicks']}")

Bulk Create URLs

import json

urls = [
    {"url": "https://shop.com/laptops", "alias": "laptops"},
    {"url": "https://shop.com/phones", "alias": "phones"}
]

response = requests.post('https://yoursite.com/api/method/utm_shortener.utm_shortener.api.bulk_create_utm_urls', {
    'campaign': 'summer_sale_campaign',
    'url_list': json.dumps(urls)
})

📊 DocTypes

UTM Campaign

Main campaign management with UTM parameters. Fields:

• Campaign Name (Data, Required)
• Campaign Code (Data, Auto-generated, Unique)
• UTM Source (Data, Required)
• UTM Medium (Select: email, social, cpc, etc.)
• UTM Campaign (Data, Required)
• UTM Term (Data, Optional)
• UTM Content (Data, Optional)
• Base URL (Data, Optional) - NEW
• Full URL with UTM Parameters (Small Text, Read-only, Auto-generated) - NEW
• Description (Text Editor)
• Status (Select: Active, Inactive, Completed)
• Start Date/End Date

Short URL

Individual shortened URLs with tracking. Fields:

• Short Code (Data, Required, Unique, Auto-generated)
• Original URL (Long Text, Required)
• Short URL (Data, Read-only, Auto-generated)
• UTM Campaign (Link: UTM Campaign, Optional)
• Generated UTM URL (Long Text, Read-only)
• Custom Alias (Data, Optional, Unique)
• Total Clicks (Int, Default: 0, Read-only)
• Status (Select: Active, Inactive, Expired)
• Expiry Date (Date, Optional)
• Last Accessed (Datetime, Read-only)

URL Click Log

Detailed click tracking records. Fields:

• Short URL (Link: Short URL, Required)
• Timestamp (Datetime, Default: now)
• IP Address (Data)
• User Agent (Long Text)
• Referrer URL (Long Text)
• Country (Data)
• City (Data)
• Device Type (Select: Desktop, Mobile, Tablet, Unknown)
• Browser (Data)
• Operating System (Data)

UTM Template

Reusable UTM parameter templates. Fields:

• Template Name (Data, Required)
• Template Code (Data, Auto-generated)
• UTM Source/Medium (Data, Required)
• UTM Campaign/Term/Content Templates (Data)
• Description (Text)
• Is Active (Check, Default: 1)

UTM Shortener Settings (Single DocType)

System-wide configuration. Fields:

• Base Domain (Data, Default: "short.ly")
• Use HTTPS (Check, Default: 1)
• Default Expiry Days (Int, Default: 365)
• Rate Limit Per Hour (Int, Default: 100)
• Enable Geolocation (Check)
• Geolocation API Key (Password)
• Blocked Domains (Long Text)

🔒 Permissions

The app includes role-based permissions:

• UTM Manager: Full access to all features
• UTM User: Create and manage own URLs
• UTM Viewer: Read-only access to analytics

⏰ Scheduled Tasks

Daily Tasks

• cleanup_expired_urls: Mark expired URLs as inactive
• update_geolocation_data: Update location data for recent clicks

Hourly Tasks

• reset_rate_limits: Reset user rate limiting counters

🎨 Customization

Adding Custom Fields

You can extend the doctypes with custom fields:

# Add custom field to UTM Campaign
custom_field = {
    "dt": "UTM Campaign",
    "properties": [
        {
            "fieldname": "budget",
            "label": "Campaign Budget",
            "fieldtype": "Currency"
        }
    ]
}

🐛 Troubleshooting

Common Issues

Short URLs not redirecting

• Check website route configuration in hooks.py
• Ensure the app is installed and migrated
• Verify domain settings

Rate limiting issues

• Check UTM Shortener Settings
• Adjust rate_limit_per_hour value

Analytics not tracking

• Verify click logs are being created
• Check browser restrictions
• Ensure proper permissions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Development Setup

# Install in development mode
bench get-app utm_shortener /path/to/local/repo
bench --site dev.local install-app utm_shortener
bench --site dev.local migrate

📄 License

MIT License - see LICENSE file for details.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

⚠️ Compatibility

• Frappe Framework: v15.0+
• ERPNext: v15.0+ (optional)
• Python: 3.8+

📝 Changelog

v1.1.0

• NEW: Auto-generate full URLs with UTM parameters
• NEW: Base URL field in UTM Campaign
• NEW: One-click copy URL functionality
• NEW: Real-time URL preview
• Improved user experience

v1.0.0

• Initial release
• Core URL shortening functionality
• UTM parameter generation
• Basic analytics
• API endpoints
• Frappe v15 compatibility

---

Made with ❤️ for the Frappe community