=== Custom Link Shortener ===

Contributors: Lukastech
Tags: url-shortener, custom-links, click-tracking, auto-linker, affiliate-links
Requires at least: 5.0
Tested up to: 7.1
Stable tag: 2.7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

URL shortener with analytics, auto-linking, smart source tracking, link cloaking, QR codes, and REST API.

== Description ==

Custom Link Shortener is a lightweight URL management, keyword auto-linking, and deep-dive analytics engine built for bloggers, marketers, and affiliate creators. 

Create custom short URLs, automatically transform keywords in your articles into trackable short links, cloak links to keep your domain in the address bar, track unique vs. repeat visitors, and monitor marketing campaigns with smart source auto-detection.

== Features ==

- 🚀 **Custom Short URLs**: Generate clean short URLs (e.g., `yoursite.com/go/offer`).
- ⚡ **Keyword Auto-Linker**: Automatically converts matching keywords in blog posts into short links with configurable limits and SEO attributes (`nofollow`, `sponsored`, `_blank`).
- 🧠 **Smart Source & Medium Auto-Detection**: Automatically identifies incoming traffic from Twitter/X, Facebook, Instagram, Google, YouTube, Reddit, LinkedIn, and Webmail even without manual UTM tags.
- 👥 **Unique vs. Repeat Tracking**: Distinguishes first-time visitors from repeat clicks with visit counts.
- 🎭 **Link Cloaking / Masking**: Keeps your branded short domain in the address bar using seamless framing.
- 🖼️ **OpenGraph Social Previews**: Custom title, description, and preview banner for social media link previews (Twitter, Facebook, Slack, LinkedIn).
- 🔲 **Instant QR Code Generation**: Download high-resolution QR codes directly from the admin dashboard for offline marketing.
- 📱 **Device, Browser & OS Parsing**: Track visitors across Windows, macOS, iOS, Android, Linux, Chrome, Safari, Edge, and Firefox.
- 🎯 **Click Goals with Email Alerts**: Set click milestones and receive automatic email alerts when targets are reached.
- ⏸️ **Instant Link Pausing**: Pause and re-activate links anytime with zero-latency AJAX toggling.
- 🔄 **A/B URL Rotation & Served Target Logs**: Rotate across multiple destination URLs and view exactly which variation was served for each click.
- 🎲 **Random Blog Post Redirection**: Route shortlinks to a random published article on your blog.
- ⏳ **Expiration & Fallback Actions**: Expire links by date/time or maximum clicks with customizable fallback redirects or custom notice pages.
- 🔒 **Password Protection**: Restrict links behind a secure password gate.
- 🛡️ **GDPR Compliance Mode**: Built-in IP anonymization to adhere to privacy regulations.
- 📁 **1-Click CSV Exports**: Download client-side CSV reports for overall performance and daily deep-dive conversion logs.
- 🔗 **Headless REST API**: Endpoints to create and manage links programmatically.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/custom-link-shortener`
2. Activate the plugin through the **Plugins** menu in WordPress
3. Navigate to **Custom Link Shortener → Settings** to configure your base slug prefix and default tracking rules
4. Create your first short link from **Custom Link Shortener**

== Screenshots ==

1. Master Analytics Dashboard with monthly growth trends, quick actions, and status toggles.
2. Partitioned Link Creation interface with Keyword Auto-Linker, UTM builders, and OpenGraph previews.
3. Daily deep-dive conversion logs with visitor types, locations, and referrer domains.
4. Instant QR code modal for high-res downloads.
5. Global settings for link routing, auto-linking rules, and GDPR compliance.

== Usage ==

=== Creating Short Links ===
1. Go to **Custom Link Shortener** in your admin menu.
2. Enter your slug and target destination URL(s).
3. (Optional) Configure Keyword Auto-Linking, UTM campaign parameters, OpenGraph social cards, or expiration rules.
4. Click **Create Short Link**.

=== Viewing Deep-Dive Analytics ===
1. Navigate to **Custom Link Shortener → Analytics**.
2. View the master Dashboard for month-over-month growth, active links, and device breakdowns.
3. Click **Report** next to any link to view daily click breakdowns.
4. Click **View Deep Dive** to see individual conversion logs with Time, Visitor Type (Unique/Repeat), Location, OS/Browser, Smart Source/Medium, and IP Address.

== External Services ==

This plugin utilizes external services for enhanced functionality:

1. **ipapi.co** (Geolocation Tracking)
- Sends: Anonymized/Visitor IP address on link click to resolve city and country.
- Terms: https://ipapi.co/terms/
- Privacy: https://ipapi.co/privacy/

2. **quickchart.io** (QR Code Rendering)
- Sends: Encoded short URL string to render the QR code modal.
- Terms: https://quickchart.io/terms/
- Privacy: https://quickchart.io/privacy/

== Frequently Asked Questions ==

=== How does Keyword Auto-Linking work? ===
When enabled, the plugin scans your published blog posts and pages in real-time and replaces keywords you specify with your short link. It respects header tags, existing anchors, code snippets, and custom per-post limits to prevent spammy links.

=== What is Smart Source Auto-Detection? ===
If a visitor clicks your link from a site like Twitter, Google, Facebook, or Reddit without explicit UTM tags attached, the plugin automatically detects the referring domain and categorizes the source and channel (e.g., `twitter / social` or `google / organic`).

=== Does UTM Pass-Through work with Google Analytics 4 (GA4)? ===
Yes. Incoming UTM parameters are forwarded directly to the destination URL while also being recorded locally in your WordPress database.

== Changelog ==

=== 2.7.0 ===
- Added Keyword Auto-Linker with site-wide and per-link controls
- Added Smart Source & Medium Auto-Detection from referrer domains
- Added Unique vs. Repeat Visitor tracking with click count badges
- Added Link Cloaking / URL Masking mode
- Added OpenGraph Social Preview metadata customization
- Added Served Target tracking for rotated URLs
- Added OS & Browser parsing (Windows, macOS, iOS, Android, Linux)
- Added GDPR Compliance Mode (IP anonymization)
- Updated compatibility for WordPress 7.1

=== 2.2.0 ===
- Added Dashboard stat trends (Month-over-Month percentage & Last Click time diff)
- Added Device/Browser parsing from raw User Agents
- Added Click Goals with email alerts
- 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

=== 2.0.0 ===
- Added Native App Deep Linking breakout
- Added Link Expiration and Fallback URLs
- Added Global Base Slug configuration via Settings Tab

== Upgrade Notice ==

=== 2.7.0 ===
Includes major analytics enhancements, Keyword Auto-Linking, Smart Source Detection, and WordPress 7.1 compatibility. No database migration required.
