document iOS shortcut

README.md

@@ -4,7 +4,57 @@ A Cloudflare Worker that removes tracking parameters from URLs using the officia
 
 ## Usage
 
-### Clean URLs
+### iOS Shortcut Integration
+
+For iPhone and iPad users, we provide a convenient iOS Shortcut that integrates directly with the system share sheet, allowing you to clean URLs from any app with just a tap.
+
+#### Installation
+
+Get it from the iCloud link: https://www.icloud.com/shortcuts/8e8fdf8350f249e488ce1fdbeab4b8b3
+When you open the link, iOS will prompt you to install the shortcut, simply tap **Add Shortcut** to complete the installation.
+
+The shortcut file is also available in this repository as `Clean URLs.shortcut` for reference.
+
+#### First Use & Permissions
+
+When you first share a URL using the shortcut, iOS will display a privacy protection dialog:
+
+> **Allow "Clean URLs" to send 1 item to "url-cleaner.m5r.workers.dev"?**
+>
+> This might allow "Clean URLs" to share this content with "url-cleaner.m5r.workers.dev" and potentially other websites.
+
+**Options:**
+- **Don't Allow** - Blocks the request (shortcut won't work)
+- **Allow Once** - Permits this single request only
+- **Always Allow** - Remembers your choice for future uses (recommended)
+
+**What this means:** iOS is asking permission for the shortcut to send your shared URL to the URL cleaner service. This is exactly what you want - the shortcut needs to send the URL to be cleaned. Choose **"Always Allow"** for the best experience.
+
+#### How to Use
+
+1. **Share a URL** from any app (Safari, Twitter, Reddit, Messages, etc.)
+2. **Find "Clean URLs"** in the share sheet (may be in the "More" section initially)
+3. **Tap the shortcut** - it will clean the URL and copy the result to your clipboard
+4. **Paste the cleaned URL** wherever you need it
+
+#### Troubleshooting
+
+**Shortcut not appearing in share sheet?**
+- Look in the "More" section (scroll right in the bottom row)
+- Open Shortcuts app → Settings → Share Sheet → ensure "Clean URLs" is enabled
+
+**Getting permission denied errors?**
+- Open Shortcuts app → find "Clean URLs" → tap the details icon (ⓘ) → **Privacy**
+- Under "Allow Get Contents of URL to use", ensure the apps you're sharing from are allowed
+- You can grant permission to specific apps or choose "Always Allow"
+
+**Cleaned URL not copying to clipboard?**
+- Open Shortcuts app → find "Clean URLs" → tap the details icon (ⓘ) → **Privacy**
+- Ensure clipboard access is enabled for the shortcut
+
+### API
+
+#### Clean URLs
 
 **API Endpoint**: `GET /?url=<encoded-url>`
 
@@ -22,7 +72,7 @@ curl "https://your-worker.workers.dev/?url=https%3A//example.com/page%3Futm_sour
 # Returns: https://example.com/page
 ```
 
-### Purge Cache
+#### Purge Cache
 
 **API Endpoint**: `DELETE /?url=<encoded-url>`
 
@@ -34,7 +84,7 @@ curl -X DELETE "https://your-worker.workers.dev/?url=https%3A//example.com%3Futm
 
 ## Features
 
-- **Official ClearURLs Rules** - Uses the same 250+ provider rule database as the ClearURLs browser extension
+- **Same ClearURLs Rules** - Uses the same 250+ provider rule database as the ClearURLs browser extension
 - **Live Rule Updates** - Automatically fetches and validates rules from ClearURLs API with SHA256 verification
 - **Query & Fragment Cleaning** - Removes tracking from both URL parameters (`?utm_source=test`) and fragments (`#utm_campaign=test`)
 - **Redirect Following** - Unwraps shortened URLs and tracking redirects (up to 5 levels)