=== Custom Link Shortener ===

Contributors: Lukastech
Tags: url-shortener, custom-links, click-tracking, utm-tracking, deep-linking, qr-codes, rest-api
Requires at least: 5.0 
Tested up to: 7.0
Stable tag: 2.2.0 
License: GPLv2 or later  
License URI: https://www.gnu.org/licenses/gpl-2.0.html  

Advanced URL shortener for WordPress with deep-dive analytics, UTM tracking, native app deep linking, link expiration, QR codes, click goals, and a REST API.

== Description ==

Advanced URL shortener for WordPress with deep-dive analytics, UTM tracking, native app deep linking, link expiration, QR codes, click goals, and a REST API.

== Features ==

- 🚀 Create custom short URLs (e.g., `yoursite.com/go/product`)
- 📱 **NEW:** Device & Browser Tracking (Desktop, Mobile, Tablet, Chrome, Safari, etc.)
- 🔲 **NEW:** Instant QR Code Generation for offline marketing
- 🎯 **NEW:** Click Goals with automated admin email alerts
- ⏸️ **NEW:** Pause/Activate links instantly via AJAX toggle
- 🗑️ **NEW:** Bulk delete functionality in the analytics dashboard
- 🔗 **NEW:** REST API endpoints for remote link creation
- 📈 Native App Deep Linking (break out of TikTok/Instagram in-app browsers)
- 🏷️ UTM Parameter Pass-Through & Local DB Tracking
- ⏳ Link Expiration with Fallback URLs
- ⚙️ Global Base Slug customization (change `/go/` to anything, or remove it)
- 📊 Detailed click analytics with:
  - UTM Source, Medium, and Campaign data
  - Visitor IP addresses and Location data (country/city)
  - User agents, devices, and browsers
- 🔄 URL rotation (randomize destinations)
- 🔒 Password protection for private links
- 📁 CSV export for all analytics data (Overview & Detailed Daily)
- 🎨 Modern Indigo Admin UI with stat cards and status badges
- 🔄 Create one URL that redirects to a random published post on your website

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/custom-link-shortener`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Navigate to WP Shortener in your admin menu to configure your Global Settings
4. Create your first short link

== Usage ==

=== Global Settings ===
1. Go to Custom Link Shortener → Settings
2. Customize your Global Base Slug (e.g., `link`, `out`, or leave blank)
3. Set your Alert Email for Click Goals
4. Toggle default behaviors for Native App Deep Linking and UTM tracking

=== Creating Short Links ===
1. Go to Custom Link Shortener in your admin menu
2. Enter your preferred alias and Destination URL(s)
3. Optional: Set Click Goals, Expiration Dates, Fallback URLs, or Passwords
4. Click "Create Short Link"

=== Viewing Analytics & Dashboard ===
1. Go to Custom Link Shortener → Analytics
2. View the master Dashboard for month-over-month trends and device breakdowns
3. Click "Report" on any link to see detailed daily stats, UTM traffic sources, and devices
4. Generate QR codes, Pause active links, or Export data as CSV directly from the table

== Advanced Features ==

=== Instant QR Codes ===
Click the "QR Code" button next to any link in your dashboard to instantly generate a scannable, downloadable QR code. Perfect for bridging offline marketing (flyers, business cards, presentations) directly to your tracked short links.

=== Click Goals & Alerts ===
Set a target number of clicks for any link. Once that threshold is reached, the plugin will automatically dispatch a notification email to your designated admin address.

=== Native App Deep Linking ===
When enabled in Settings, the plugin attempts to force links opened inside social media platforms (like TikTok, Instagram, or Pinterest) to break out of the restrictive in-app browser and open in the user's native browser or native destination app.

=== UTM Tracking & Pass-Through ===
The plugin automatically catches incoming UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`), logs them into your local WordPress database for easy viewing alongside device data, and seamlessly forwards them to your final destination URL so external tools like Google Analytics (GA4) can still track them.

=== REST API Integration ===
Manage links headlessly via the WordPress REST API:
- `GET /wp-json/wpcs/v1/links`: Retrieve all links
- `GET /wp-json/wpcs/v1/links/{id}`: Retrieve a specific link
- `POST /wp-json/wpcs/v1/links`: Create a new link (requires authentication)

=== URL Rotation & Random Posts ===
- Enter multiple URLs to randomize destinations on every click (A/B Testing)
- Use the Random Post feature to route visitors to a random published article on your site

== Screenshots ==

1. Link creation screen showing configuration fields and inline base URL slug row.
2. Dashboard overview displaying month-over-month traffic trends and active links.
3. Comprehensive global device, browser, and hardware environment breakdowns.
4. Detailed active link dashboard with controls.
5. In-depth UTM traffic logging display and alert notification settings.

== External Services ==

This plugin uses external services for enhanced functionality:

1. **ipapi.co** (Location Tracking)
- Sends: Visitor's IP address (only when a link is clicked)
- Terms: https://ipapi.co/terms/
- Privacy: https://ipapi.co/privacy/

2. **goqr.me / qrserver.com** (QR Generation)
- Sends: The short URL string to generate the image
- Terms: https://goqr.me/api/

== Frequently Asked Questions ==

=== Can I use custom slugs? ===
Yes! You can choose any alphanumeric slug. You can also customize the base slug (e.g., change `/go/` to something else) in the Settings tab.

=== Does UTM tracking conflict with Google Analytics? ===
No! The UTM Pass-Through feature ensures that GA4 receives the exact same tracking data, while giving you a resilient, server-side backup inside your WordPress dashboard that defeats ad-blockers.

=== How do I pause a link? ===
Simply toggle the switch in the Analytics overview table. Paused links will immediately stop redirecting traffic and display an inactive message to visitors.

== Changelog ==

=== 2.2.0 (May 2026) ===
- Added Dashboard stat trends (Month-over-Month percentage & Last Click time diff)
- Added Device/Browser parsing from raw User Agents
- Added Click Goals (Email alert when target is hit)
- Added Link Pausing/Deactivation (AJAX Toggle)
- Added Bulk Delete checkboxes to Analytics
- Added REST API endpoints for remote link generation
- Added Instant QR Code generation via interactive modals
- Redesigned admin UI with modern indigo design system, stat cards, and status badges
- Improved clipboard feedback with toast notifications

=== 2.0.1 (May 2026) ===
- Fixed analytics layout constraints
- Upgraded UTM feature to log parameters locally to the database
- Added Traffic Source (UTMs) to CSV exports
- Added auto-migration for database upgrades

=== 2.0.0 (May 2026) ===
- WordPress 7.0 Compatibility
- Added Native App Deep Linking breakout
- Added Link Expiration and Fallback URLs
- Added Global Base Slug configuration via new Settings Tab

=== 1.4.3 (June 2025) ===
- Redirect users to random posts on the website via a shortlink
- Added Total Redirects tracking

=== 1.4.0 (May 2025) ===
- Complete UI redesign and CSV export addition

== Support ==

For support, please email support@lukastechs.com.

---

Pro Tip: For maximum compatibility, always test new short links before sharing them widely!