=== Custom Link Shortener ===
Contributors: lukastech
Tags: url-shortener, link-management, click-tracking, qr-code, redirect
Requires at least: 5.0
Tested up to: 7.0
Stable tag: 2.2.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Advanced URL shortener with analytics, link rotation, QR codes, click goals, UTM tracking, and deep linking.

== Description ==

Advanced URL shortener for WordPress. Create trackable short links with rotation, QR codes, click goals, UTM pass-through, device analytics, link expiry, password protection, and a REST API.

**Core Features**

* Create custom short URLs (e.g., `yoursite.com/go/product`)
* Device & Browser Tracking (Desktop, Mobile, Tablet, Chrome, Safari, etc.)
* Instant QR Code generation for offline marketing
* Click Goals with automated admin email alerts
* Pause/Activate links instantly via AJAX toggle
* Bulk delete functionality in the analytics dashboard
* REST API endpoints for remote link creation
* Native App Deep Linking (breaks out of TikTok/Instagram in-app browsers)
* UTM Parameter Pass-Through and Local DB Tracking
* Link Expiration with Fallback URLs
* Global Base Slug customization (change `/go/` to anything, or remove it)
* Detailed click analytics: UTM data, IP geolocation, user agents, devices, browsers
* URL Rotation for A/B testing across multiple destinations
* Password protection for private links
* CSV export for all analytics data
* Modern admin UI with stat cards and status badges

== 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 **Link Shortener** in your admin menu
4. Visit **Settings** to configure your base slug and default behaviours
5. Create your first short link

== Usage ==

= Global Settings =

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

= Creating Short Links =

1. Go to **Link Shortener** in your admin menu
2. Enter your preferred alias and destination URL(s)
3. Optionally set a Click Goal, Expiration Date, Fallback URL, or Password
4. Click **Create Short Link**

= Viewing Analytics =

1. Go to **Link Shortener → Analytics**
2. View the overview dashboard for month-over-month trends and device breakdowns
3. Click **Report** on any link for detailed daily stats, UTM sources, and device data
4. Generate QR codes, pause links, or export CSV directly from the table

== Advanced Features ==

= Instant QR Codes =

Click the QR Code button next to any link to generate a scannable, downloadable QR code — ideal for bridging offline marketing (flyers, business cards, presentations) to your tracked short links.

= Click Goals & Alerts =

Set a target click count for any link. Once the threshold is reached, the plugin dispatches a notification email to your designated admin address automatically.

= Native App Deep Linking =

When enabled, the plugin attempts to force links opened inside social media platforms (TikTok, Instagram, Pinterest) to break out of the in-app browser and open in the user's native browser or native app.

= UTM Tracking & Pass-Through =

Incoming UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`) are captured server-side, logged to your local WordPress database, and forwarded to the destination URL so tools like Google Analytics (GA4) still receive them — even when ad-blockers are active.

= REST API =

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 destination URLs to randomize on every click (A/B testing)
* Use the Random Post feature to route visitors to a random published article

== External Services ==

This plugin connects to two external services:

**ipapi.co** — Used for visitor geolocation (country and city lookup).

* Data sent: visitor IP address, on each link click
* Terms of service: https://ipapi.co/terms/
* Privacy policy: https://ipapi.co/privacy/

**goqr.me / qrserver.com** — Used for QR code image generation.

* Data sent: the short URL string
* API documentation: https://goqr.me/api/

== Frequently Asked Questions ==

= Can I use custom slugs? =

Yes. You can choose any alphanumeric alias. You can also change the base slug (e.g., swap `/go/` for anything you prefer) in the Settings tab.

= Does UTM tracking conflict with Google Analytics? =

No. The UTM Pass-Through feature ensures GA4 still receives the same tracking parameters, while also storing a server-side backup in your WordPress database that is not affected by ad-blockers.

= How do I pause a link? =

Toggle the switch next to any link in the Analytics overview. Paused links stop redirecting immediately and show an inactive message to visitors.

= What happens when a link expires? =

If you set a Fallback URL, visitors are redirected there. If no fallback is set, they are redirected to your homepage.

== Screenshots ==

1. Link creation screen with inline base URL slug row and configuration fields.
2. Analytics overview showing month-over-month traffic trends and active link table.
3. Global device, browser, and hardware breakdown panel.
4. Detailed per-link dashboard with controls, QR code, and pause toggle.
5. UTM traffic source log and click goal alert settings.

== Changelog ==

= 2.2.0 =
* Added dashboard stat trends (month-over-month percentage and last click time)
* Added device and browser parsing from raw user agents
* Added click goals with email alerts when target is reached
* Added link pausing and deactivation via AJAX toggle
* Added bulk delete with checkboxes in the analytics table
* Added REST API endpoints for remote link management
* Added instant QR code generation via modal
* Redesigned admin UI with indigo design system, stat cards, and status badges
* Improved clipboard feedback with toast notifications

= 2.0.1 =
* Fixed analytics layout constraints
* Upgraded UTM feature to log parameters locally to the database
* Added UTM columns to CSV exports
* Added auto-migration for database schema upgrades

= 2.0.0 =
* Added native app deep linking breakout
* Added link expiration with fallback URLs
* Added global base slug configuration via Settings tab

= 1.4.3 =
* Added random post redirect feature
* Added total redirects tracking

= 1.4.0 =
* Complete UI redesign
* Added CSV export for analytics data

== Upgrade Notice ==

= 2.2.0 =
Major feature update. Database schema is auto-migrated on activation. No manual steps required.