UTM Shortener - Enterprise URL Management & Analytics

A powerful, self-hosted URL shortening and UTM campaign management solution for Frappe/ERPNext. Track marketing campaigns, analyze traffic sources, and optimize conversions with enterprise-grade analytics.

🚀 Key Features

URL Management

• Custom Branded Domains: Use your own domain for short URLs
• Flexible Short Codes: Auto-generated or custom aliases
• Bulk Operations: Create hundreds of URLs at once
• QR Code Generation: Automatic QR codes for every URL
• URL Expiration: Set time limits for temporary campaigns

Campaign Tracking

• Full UTM Support: Source, Medium, Campaign, Term, Content
• Campaign Organization: Group URLs by marketing campaigns
• Template System: Reusable UTM parameter sets
• Multi-channel Tracking: Track performance across all channels

Analytics & Insights

• Real-time Analytics: See clicks as they happen
• Conversion Source Tracking: Know where your traffic comes from
• Geographic Analytics: Track visitor locations
• Device & Browser Stats: Understand your audience
• Campaign ROI: Measure campaign effectiveness

Enterprise Features

• Self-hosted: Complete control over your data
• Rate Limiting: Prevent abuse and spam
• Permission Control: Role-based access
• API Access: Full REST API for integrations
• Scheduled Cleanup: Automatic maintenance

📋 Prerequisites

• Frappe/ERPNext v14 or higher
• Python 3.8+
• MariaDB/MySQL
• Redis

🛠️ Installation

Option 1: Frappe Cloud (Recommended)

Install directly from the Frappe Cloud marketplace - no server configuration needed!

See FRAPPE_CLOUD_SETUP.md for detailed instructions.

Option 2: Self-Hosted

# Install the app
bench get-app https://github.com/chinmaybhatk/utm_shortener.git
bench --site your-site-name install-app utm_shortener

# Run migrations
bench --site your-site-name migrate

For production deployment, see DEPLOYMENT.md.

⚙️ Quick Setup

1. Configure Your Domain

Go to UTM Shortener Settings and configure:

For Frappe Cloud:

Short Domain: your-site.frappe.cloud
Use HTTPS: ✓
Custom Domain Enabled: ☐

For Self-Hosted:

Short Domain: link.yourdomain.com
Use HTTPS: ✓
Custom Domain Enabled: ✓

2. Create Your First Campaign

# Create a campaign
campaign = frappe.get_doc({
    "doctype": "UTM Campaign",
    "campaign_name": "Product Launch 2024",
    "utm_source": "social",
    "utm_medium": "post",
    "utm_campaign": "product-launch-2024"
}).insert()

# Create a short URL
short_url = frappe.get_doc({
    "doctype": "Short URL",
    "original_url": "https://example.com/new-product",
    "utm_campaign": campaign.name,
    "custom_alias": "new-product"
}).insert()

print(f"Your short URL: {short_url.short_url}")

3. URL Structure

Frappe Cloud URLs:

https://your-site.frappe.cloud/s/new-product

Self-Hosted URLs:

https://link.yourdomain.com/s/new-product

Custom Domain (with Cloudflare Worker):

https://short.link/new-product

📊 How It Works

graph LR
    A[Create Campaign] --> B[Generate Short URLs]
    B --> C[Share in Marketing]
    C --> D[Visitor Clicks]
    D --> E[Track Analytics]
    E --> F[Redirect to Target]
    E --> G[Dashboard Reports]

Loading

🌐 Deployment Options

1. Frappe Cloud (Easiest)

• No server management
• Automatic SSL
• Built-in scaling
• Works out of the box

2. Self-Hosted

• Full control
• Custom nginx configuration
• Any domain structure

3. Hybrid (Frappe Cloud + Custom Domain)

• Use Cloudflare Workers for custom domains
• Keep app on Frappe Cloud
• Best of both worlds

See our Cloudflare Worker example for custom domain setup.

📚 Documentation

• Setup Guide - Detailed setup instructions
• Frappe Cloud Setup - Frappe Cloud specific guide
• Deployment Guide - Self-hosted production deployment
• Workflow Documentation - Visual workflow diagrams
• API Reference - Complete API documentation

🔧 API Reference

Authentication

All API calls require authentication using API keys or session tokens.

Core Endpoints

Create UTM Campaign

POST /api/method/utm_shortener.utm_shortener.api.create_utm_campaign
{
    "campaign_name": "Summer Sale",
    "utm_source": "email",
    "utm_medium": "newsletter",
    "utm_campaign": "summer-sale-2024"
}

Create Short URL

POST /api/method/utm_shortener.utm_shortener.api.create_short_url
{
    "original_url": "https://example.com/page",
    "utm_campaign": "campaign-id",
    "custom_alias": "summer"
}

Get Analytics

GET /api/method/utm_shortener.utm_shortener.api.get_campaign_analytics
{
    "campaign_id": "campaign-id"
}

🎯 Use Cases

Marketing Teams

• Track campaign performance across channels
• A/B test different messaging
• Measure ROI by traffic source

Sales Teams

• Create personalized links for prospects
• Track engagement with sales materials
• Measure email campaign effectiveness

Social Media

• Track viral content spread
• Measure influencer campaign impact
• Optimize posting strategies

Events & Webinars

• Track registration sources
• Measure promotional effectiveness
• Analyze attendee demographics

🔒 Security & Privacy

• Self-hosted: Your data stays on your servers
• Permission-based: Granular access control
• GDPR Compliant: Full data ownership and control
• Rate Limiting: Built-in abuse prevention
• Audit Trail: Complete activity logging

📈 Analytics Dashboard

Track comprehensive metrics:

• Traffic Sources: Social, Search, Email, Direct
• Geographic Distribution: Country-level tracking
• Device Analytics: Desktop, Mobile, Tablet
• Time Analysis: Peak traffic hours
• Conversion Tracking: Source to conversion mapping

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the robust Frappe Framework
• Inspired by modern URL shorteners like Bitly and Rebrandly
• Community contributors and testers

📞 Support

• Documentation: All Guides
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Frappe Cloud Support: support@frappe.cloud

🌟 Star History

---

Made with ❤️ for the Frappe/ERPNext community