QR Redirect Service - Developer Guide
Overview
The QR Redirect Service is a Cloudflare Worker-based application that enables seamless URL sharing between devices using QR codes. It's designed to solve the common problem of transferring URLs from mobile devices to desktop browsers or between different devices without typing or messaging.
How It Works
Service Architecture
- QR Code Generation: The service generates a unique redirect ID and creates a QR code containing a special URL
- Real-time Polling: The browser continuously polls the server to check for incoming URLs
- URL Transmission: When a device scans the QR code and submits a URL, it's stored temporarily in Cloudflare KV
- Automatic Redirect: The browser detects the new URL and automatically redirects to it
- Cleanup: URLs are automatically deleted after use or expiration for security
API Endpoints
GET /
Purpose: Generate a new QR redirect session
Response: HTML page with QR code and polling functionality
Behavior: Creates a unique 12-character redirect ID and displays the QR code page
GET /send_url
Purpose: Handle QR code display and URL submission
Parameters:
- redirect_id (required) - Unique session identifier
- url (optional) - Target URL to redirect to
Behavior:
- Without url: Shows QR code page for the given redirect_id
- With url: Stores the URL and responds with success message
GET /check_status
Purpose: Poll for URL availability
Parameters:
- redirect_id (required) - Session identifier to check
Response Examples:
// Waiting for URL
{"status": "waiting"}
// URL ready for redirect
{"status": "ready", "url": "https://example.com"}
GET /developer-guide
Purpose: Display this developer documentation
Response: HTML page with comprehensive API documentation and usage examples
Usage Flow
Step-by-Step Process
- Browser: User visits the service URL (e.g.,
https://your-worker.workers.dev/)
- Service: Generates unique redirect ID (e.g.,
abc123xyz789)
- QR Code: Displays QR code containing:
https://your-worker.workers.dev/send_url?redirect_id=abc123xyz789&url=
- Mobile Device: Scans QR code and opens the URL in a browser/app
- User Input: User appends target URL:
...&url=https://example.com
- Storage: Service stores the URL in Cloudflare KV with 60-second TTL
- Polling: Original browser detects the URL via polling every 2 seconds
- Redirect: Browser automatically redirects to
https://example.com
- Cleanup: URL is immediately deleted from storage after retrieval
Integration Examples
Basic HTML Integration
<!-- Embed QR redirect in your webpage -->
<iframe src="https://your-worker.workers.dev/" width="500" height="600"></iframe>
Mobile App Integration
// JavaScript example for mobile apps
const qrUrl = "https://your-worker.workers.dev/send_url?redirect_id=abc123&url=";
const targetUrl = "https://example.com";
const fullUrl = qrUrl + encodeURIComponent(targetUrl);
// Open in browser or webview
window.open(fullUrl, '_blank');
API Integration
// Send URL programmatically
const response = await fetch('https://your-worker.workers.dev/send_url', {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
});
// Check status
const statusResponse = await fetch('https://your-worker.workers.dev/check_status?redirect_id=abc123');
const status = await statusResponse.json();
Security Features
Built-in Security Measures
- Time-based Expiration: URLs automatically expire after 60 seconds
- Single-use URLs: URLs are deleted immediately after being retrieved
- URL Validation: Only valid URL formats are accepted
- CORS Protection: Configurable cross-origin resource sharing
- No Persistent Storage: No long-term data retention
- Random Session IDs: 12-character random identifiers prevent guessing
Use Cases
1. Cross-Device URL Sharing
Share links from mobile devices to desktop browsers without typing or messaging apps.
2. Presentation Tools
Allow audience members to send URLs to a presenter's screen during meetings or conferences.
3. Digital Signage
Enable visitors to send content to public displays or kiosks.
4. IoT Device Control
Send configuration URLs or commands to IoT devices with camera capabilities.
5. Customer Support
Allow customers to quickly share problematic URLs with support representatives.
6. Educational Tools
Students can share research links with classroom displays or teacher devices.
Troubleshooting
Common Issues
- QR Code Not Scanning: Ensure the QR code is clear and the camera has good lighting
- URLs Not Redirecting: Check that the redirect_id matches and hasn't expired (60-second limit)
- Invalid URLs: Make sure the URL includes the protocol (http:// or https://)
- Mobile Browser Issues: Some mobile browsers may block automatic redirects - try manually opening the URL
Best Practices
- URL Format: Always include the full URL with protocol (e.g., https://example.com)
- Timing: Complete the URL submission within 60 seconds of generating the QR code
- Network: Ensure both devices have stable internet connections
- QR Code Size: Display QR codes large enough for easy scanning (recommended minimum 200x200px)
Service Limitations
- URLs expire after 60 seconds for security
- Each QR code can only be used once
- Service requires internet connectivity on both devices
- Maximum URL length supported: 2048 characters