Using CirculateQR

📊 Dashboard

The Dashboard is your command center — the first thing you see after logging in. It provides a real-time overview of your entire QR code operation in a two-column layout optimized for quick decision-making.

Welcome Header

At the top of the dashboard, you'll see a personalized greeting based on the time of day ("Good morning, Keith") and a prominent Create QR button that takes you directly to the Studio. Below the greeting, the system tells you what's happening at a glance — like "2 QR codes expiring soon" or "14 new scans today."

Expiring QR Alerts

If you have any QR codes approaching their expiration date (common on the free tier where codes are hosted temporarily), a yellow/amber alert bar appears below the header. Each alert shows the QR code name, expiration date, and a one-click action to either unlock it permanently ($5 one-time) or upgrade your plan. This ensures you never lose a QR code that's already in circulation.

Smart Overview Header (Stats Row)

A full-width stats bar shows your most important metrics at a glance:

Each stat card is interactive — clicking it navigates to the relevant deep-dive page (e.g., clicking "Total Scans" goes to Analytics).

Below the stats row, a breakdown of QR types (Business Cards, Menus, WiFi, Events, Links) shows colored pill badges with counts for each category, giving you a portfolio overview of what types of codes you're deploying.

Global Scan Map

The left column features a large, interactive world map that visualizes your scans geographically. Each scan appears as a glowing dot on the map, color-coded by device type (mobile = cyan, desktop = purple, tablet = green). The map updates in near-real-time and supports zoom/pan. A "Full Analytics" link in the top-right corner of the map panel takes you to the dedicated analytics page.

Live Activity Feed

Below the map, the Live Activity Feed shows a chronological stream of recent scan events across all your QR codes. Each entry displays:

• QR code name and short ID that was scanned
• Device type (iPhone, Android, Desktop) with browser identification
• Geographic location (city, country) with flag emoji
• Timestamp showing relative time ("2 minutes ago", "1 hour ago")
• Which destination the scanner was redirected to
• Which workflow rule triggered (if any automation fired)

The feed auto-refreshes and supports clicking on any entry to jump to that QR code's detail page.

Quick Actions Panel

In the right sidebar column, a grid of 6 quick-action cards provides one-click navigation to the most common tasks:

Automation Health Panel

Below the quick actions, the Automation Health Panel provides a live status dashboard for all your active workflow rules. It shows:

• Rule type with icon (Time Routing ⏰, Geo Routing 🌍, Device Routing 📱, A/B Testing 🔀, Password Gate 🔒, Age Verification 🔞, Scheduled 📅)
• Status indicator — green dot for healthy/active, yellow for degraded, red for errored
• Trigger count — how many times each rule has fired
• Last triggered timestamp
• Quick toggle to enable/disable individual rules

Onboarding Wizard (New Users)

If this is your first time and you have zero QR codes, the dashboard doesn't show the command center view. Instead, it displays a guided Onboarding Wizard that walks you through:

1. Welcome screen with a greeting and platform overview
2. Create your first QR code — the wizard pre-fills a URL type code and guides you through the Studio
3. Download & share — shows you how to download the QR image and deploy it
4. Track & optimize — introduces the analytics dashboard and how to read scan data

Once you create your first QR code, the wizard automatically dismisses and the full command center view appears.

✨ Creating QR Codes

CirculateQR offers two paths for creating QR codes: the Quick Generator at /create for traditional QR creation, and the AI Studio at /studio for AI-powered artistic QR design. This section covers the Quick Generator — see the AI Studio section for the full-featured design experience.

Step 1: Choose QR Type

The first step is selecting what kind of data your QR code will encode. Each type is represented by a card with an icon and description:

Step 2: Enter Content

Based on the type you selected, a form appears for the relevant data:

• URL: A text field for the destination URL (e.g., https://your-website.com)
• WiFi: Fields for Network Name (SSID), Password, and Security type (WPA/WPA2/WEP/None)
• Contact Card: Full form with First Name, Last Name, Phone, Email, Company, Job Title, Address, Website, and Notes fields
• Event: Event Name, Start Date/Time, End Date/Time, Location, and Description
• SMS: Phone Number and pre-filled Message Body
• Email: To Address, Subject Line, and Email Body

A live preview of the QR code updates in real-time as you type, so you can see exactly what the final code will look like before generating.

Step 3: Customize Design

After entering your content, the design customization panel opens. Options depend on the style you pick:

Basic (every plan)

• Foreground and background colour pickers
• Module shape: square, rounded or circle (the corner markers follow the same shape)
• Size: small (256px), medium (512px) or large (1024px)
• A static code is free; a dynamic code costs 1 QR credit

Branded (Studio plan and up)

• Everything in Basic, plus your logo in the centre (PNG, JPG, WebP or GIF up to 5MB)
• Primary and secondary brand colours
• Costs 2 QR credits

AI art (any plan with AI credits)

• Describe a scene or start from one of 124 AI scene templates, and Gemini builds the code into the artwork
• Every image is decoded after generation and must read back the exact link; if it doesn't, the real code is redrawn into the same spot with matching perspective and lighting, then checked again
• Reference images guide the style: Studio 3, Artisan 8, Stealth 13
• 1 AI credit per image, 4 for 4K (Artisan and Stealth), +1 with Google Search grounding
• AI credits come with Studio (10 a month) and higher plans. The free plan includes none, but AI credit packs can be bought on any plan, including Free

Step 4: Add Smart Features

Before generating, you can enable advanced routing and access-control features. These features apply to dynamic QR codes only:

Step 5: Preview & Generate

The final step shows a full preview of your QR code with all settings applied. You can see:

• The rendered QR code at full resolution (512×512)
• All enabled smart features listed below the preview
• Credit cost breakdown for this generation
• Your remaining credit balance after generation

Click Generate QR Code to create the code. Once generated, you get options to:

• Download as PNG (every style)
• Download as SVG (Basic style only)
• Download an A4 PDF print sheet
• Copy the short URL to clipboard (e.g., circulateqr.com/go/abc123)
• The code also automatically appears in your My Codes library

▦ My Codes

My Codes is your QR code library — a centralized inventory of every code you've ever created. It's designed for fast bulk management whether you have 5 codes or 5,000.

Page Header

At the top of the page, you see your total code count and cumulative scan count (e.g., "24 codes • 12,340 total scans"). A prominent Create QR button links to the Studio for new code creation.

Toolbar

Below the header, a horizontal toolbar provides four controls for managing your view:

Search

A full-width search bar lets you search codes by name or short ID. Type "menu" to instantly filter to all menu-related QR codes. The URL updates with a ?q= parameter so you can bookmark filtered views or share them with teammates.

Status Filter

A segmented toggle lets you filter by status:

• All — show every QR code regardless of status
• Active — only show codes that are live and scannable
• Paused — only show codes that have been temporarily disabled (scans are blocked but data is preserved)

Sort Options

A dropdown lets you re-order your code list:

View Toggle

Switch between two layout modes — your preference is saved to localStorage and persists across sessions:

• List View (☰) — a spreadsheet-style table with columns for checkbox, QR thumbnail, name/short URL, scan count, last scan time, status badge, and action buttons. Best for managing many codes at once.
• Grid View (⊞) — card-based layout showing each code as a tile with a large QR thumbnail, name, type badge, scan count, and quick-action icons. Best for visual browsing and presentation.

List View Columns

In list view, each row displays a comprehensive data snapshot:

Grid View Cards

In grid view, codes display as responsive tiles (2 columns on mobile, up to 5 on desktop). Each card shows:

• A large square QR thumbnail area (aspect-ratio 1:1) with a green/red status dot in the top-right corner
• A selection checkbox in the top-left corner
• An "AI Artisan" badge if the code was generated using the artisan tier
• Code name with a type badge (URL, WiFi, vCard, etc.)
• Short link in cyan text
• Scan count and quick action buttons (download, copy) along the bottom

Quick Actions Per Code

Every code — in either view — offers three inline actions:

Bulk Selection & Delete

For mass operations, use the checkbox on each row or the "select all" checkbox in the list header. When one or more codes are selected, a cyan action bar appears showing:

• Selection count ("3 selected")
• Delete button — opens a destructive confirmation modal
• Clear selection — deselects all codes

Delete Confirmation Modal

Deleting QR codes is irreversible, so the platform enforces a strict confirmation flow:

1. A modal overlay appears with a red warning icon
2. The modal explains that all analytics data and short links will be permanently deleted
3. You must type the exact phrase "Delete QR" into a text input to confirm
4. Only when the input matches does the "Delete Forever" button become active (red)
5. On confirmation, the codes are permanently removed and disappear from the list

Empty State

If you have no codes (or your search returns zero results), a beautiful empty-state screen appears with an animated QR icon, a prompt to create your first code, and three highlight cards explaining the platform's key capabilities (Real-time Analytics, Smart Workflows, AI-Powered Design).

🎨 AI Studio (Studio v5)

The AI Studio is CirculateQR's flagship creative tool — a full-screen, three-panel "dual cockpit" interface where you design, configure, and deploy AI-powered QR codes. It's the most advanced QR code designer available, combining a behavioral automation engine with an AI art forge.

Layout Architecture

The Studio fills the entire viewport and is divided into three persistent panels plus a bottom action bar:

Left Panel — Behavior Engine

The left panel has two modes toggled at the top: Quick Mode (simplified) and Advanced Mode (full N×N workflow builder).

Destination Types

Choose what kind of experience the scanner lands on. Each type customizes the content form below:

Automation Blocks (Quick Mode)

In Quick Mode, you toggle pre-built automation blocks on/off with simple switches. Each block adds a behavior layer to your QR code:

Advanced Mode — Visual Workflow Builder

For power users, Advanced Mode reveals a visual node-based canvas. You build scan logic as a flowchart of connected nodes:

• Trigger Node — the entry point (always "QR Code Scanned")
• Condition Nodes — decision diamonds that branch based on device type, time, location, scan count, etc.
• Destination Nodes — the final redirect URL for that branch
• Drag edges between nodes to connect them. Each edge can have a label (e.g., "iOS", "After 6pm")

The workflow builder validates your graph in real-time, warning about disconnected nodes, infinite loops, or missing destinations.

Center Stage — Live Preview

The center panel is your real-time preview area. It shows:

• A large, live-rendered QR code that updates as you change settings on either side panel
• The current generation tier badge (Basic, Branded, or Artisan) with credit cost
• A dotted grid background that helps visualize alignment and sizing
• During AI generation: a progress indicator with status messages ("Generating...", "Verifying scannability...", "Recovering failed modules...")

Generation Gallery

Below the main preview, a horizontal gallery strip shows all generated variants for the current project. Each variant displays as a thumbnail that you can:

• Click to select as the active version (shown in the main preview)
• Compare side-by-side with other variants
• See the scannability verification status (green check = verified, yellow = recovered, red = failed)
• See the decoded payload to confirm it points to the correct URL
• View generation time and timestamp

Right Panel — Artisan Forge

The right panel controls the visual design of your QR code. It adapts based on which generation tier is selected:

Generation Tiers

Basic Tier Controls

• Shape — square, rounded, or circle module style
• Size — small (256px), medium (512px), or large (1024px)
• Foreground color picker with hex input
• Background color picker with hex input

Branded Tier Controls

Everything from Basic, plus:

• Logo Upload — drag-and-drop or click to upload your brand logo (PNG, JPG, WebP or GIF, up to 5MB)
• Primary & Secondary colour pickers

Artisan Tier Controls

The AI creative suite:

• Template Browser — browse marketplace templates by category (Restaurant, Real Estate, Events, etc.) and apply them as starting points
• Scene Prompt — free-text description of the scene you want ("a cozy Italian restaurant with warm lighting and checkered tablecloths")
• Embedded Text — optional text to render within the artwork (e.g., your restaurant name)
• Style Mode — Photorealistic, Cinematic, Artistic, Vintage, or Modern
• QR Size — how large the QR code appears within the artwork (Tiny, Small, Medium, Large)
• Density — QR data density (Low = simpler/larger modules, Standard, High = more data capacity)
• Resolution — 2K on every plan (1K requests are raised to 2K so the code has enough detail); 4K on Artisan (10 a month) and Stealth (50 a month)
• Aspect Ratio — 1:1, 4:3, 3:4, 16:9 or 9:16
• Variations — how many versions to generate at once (1, 2 or 4)

Reference Images

From the Studio plan you can add reference images (Studio 3, Artisan 8, Stealth 13), each with detailed controls:

• Purpose tag — classify each image as Style, Subject, Environment, Product, or Color reference
• Intensity slider — Strong (heavily influence output), Balanced, or Subtle (light touch)
• Apply To checkboxes — choose which aspects to transfer: Lighting, Colors, Textures, Composition, Mood
• Quick Presets — one-click options like "Match Lighting", "Extract Colors", "Same Vibe", "Clone Subject"
• Description — optional text explaining what you want extracted from this reference

Advanced AI Controls

• Search Grounding — let the AI use Google Search for context about your brand or prompt (Artisan and Stealth, +1 AI credit)
• Pure AI Mode — keep the raw AI output and skip the scan correction
• Template Variables — when using a marketplace template, a dynamic form appears for customizing template-specific fields (e.g., "Restaurant Name", "Cuisine Type")

Bottom Action Bar

The fixed bottom bar spans the entire Studio width and contains:

• Save Draft — saves the current project state without generating
• Preview — opens a full-screen preview of the current QR code
• Generate — triggers AI generation based on current settings. Shows credit cost and remaining balance.
• Deploy — publishes the selected generation as a live QR code (creates the short URL, activates routing rules, and adds to My Codes)

Deploy Success Dialog

After deploying, a success dialog appears with:

• The generated QR code image at full resolution
• The live short URL (e.g., circulateqr.com/go/abc123)
• One-click buttons: Download PNG (and SVG for Basic codes), Copy URL
• A link to the code in My Codes for future management
• Quick links to set up Workflows or view Analytics for this code

⚡ Workflows & Automation

Workflows let you add routing rules to any dynamic QR code — no code required. When someone scans the code, the routing engine evaluates each rule in priority order and redirects accordingly.

How Workflows Work

1. Navigate to Dashboard → Workflows, or access workflows directly from a QR code's settings
2. Click "+ Create Workflow" and select a QR code to attach it to
3. Add one or more routing rules — each rule has a condition (e.g., "device is iOS") and an action (redirect to a specific URL)
4. Rules are evaluated top-to-bottom by priority. The first matching rule wins. If no rules match, the default URL is used.

Available Rule Types

Matching rules can redirect, split traffic for an A/B test, show a password, email or age gate, fire your retargeting pixel, or call your webhook. Bot scans are left out of analytics.

📊 Analytics Engine

The Analytics Engine is a 7-tab intelligence dashboard that provides real-time visibility into how your QR codes perform across devices, regions, and time periods.

Overview Tab

Your command center. Shows key metrics (total scans, unique visitors, new vs. returning, peak hour, countries, active codes), a scan timeline, and a 7×24 hourly heatmap.

Audience Tab

Deep-dive into who is scanning your codes. Includes device breakdown (mobile/desktop/tablet), operating system distribution, browser fingerprints, language preferences, and Scanner Persona Profiles — groups of scanners by device and time of day, like "iPhone Afternoon Scanners."

Codes Tab

Per-code performance analysis with a ranked leaderboard (including Health Scores 0-100), Code Lifecycle tracking (time to first scan), and Code vs. Code Comparison — a side-by-side table comparing scans, unique visitors, top device, peak hour and top country for every code.

Geography Tab

Interactive Mapbox-powered world map showing scan density by country and city. Drill down into regions, view city-level granularity, and identify geographic clusters. Requires NEXT_PUBLIC_MAPBOX_TOKEN for map rendering.

Sources Tab

Traffic attribution showing referrer domains, UTM campaign tracking, cross-QR visitor overlap rates, and multi-code visitor analysis. Understand whether your QR codes share audiences or serve distinct channels.

Live Feed Tab

Real-time stream of the last 100 scan events. Each entry shows the QR code name, device, OS, browser, country, city, timestamp, and whether it was a new or returning visitor. Auto-refreshes when the tab is active.

AI Insights Tab ✨

The premium intelligence layer. Uses Google Gemini to analyze your complete analytics profile and generate a strategic briefing. Costs 2 AI credits per report.

What You Get

• Program Health Score (0-100) with 5-dimension breakdown: Reach, Engagement, Growth, Efficiency, Diversity
• Executive Summary headline with industry benchmark positioning
• 5-7 Strategic Findings with impact ratings (HIGH/MEDIUM/LOW), detailed analysis, and specific recommendations
• Suggested Experiments with hypotheses and expected lift percentages
• Weekly Intelligence Digest — a 4-5 paragraph professional briefing
• Drill-Down Q&A — ask follow-up questions (1 credit each) with AI-suggested conversation chains

Post-Scan Pixel SDK

The Pixel SDK is automatically injected into every QR code landing page (/view/[shortId]). It captures post-scan engagement without any setup:

• Page view tracking with viewport and referrer data
• Scroll depth milestones (25%, 50%, 75%, 100%)
• CTA click tracking on links and data-cqr-track elements
• Dwell time measurement via sendBeacon on page exit
• Manual conversion tracking via window.__cqr.track("purchase", 99.99)

Data Capture

Every scan captures 15+ data points automatically:

📄 Content & Pages

Create hosted landing pages that can be linked to your QR codes. Pages are fully managed by CirculateQR — no external hosting needed.

Creating a Page

1. Navigate to Dashboard → Pages
2. Click "+ New Page" and choose a template or start blank
3. Add content blocks: text, images, buttons, forms, videos, maps, social links
4. Customize colors, fonts, and layout to match your brand
5. Publish and link to any QR code as its destination URL

📱 QR Code Types

CirculateQR supports 13 specialized QR code types, each with dedicated landing page templates and unique interaction models:

🦎 Smart Routing (Chameleon Engine)

The Chameleon Engine is the brain behind every QR code scan. When a user scans any CirculateQR code, the engine runs in real-time to determine the optimal destination.

How It Works

1. User scans your QR code → the short URL (e.g., circulateqr.com/go/abc123) is hit
2. Chameleon extracts scan context: device, OS, language, country, region, city, time, UTM params
3. If workflows are attached, rules are evaluated top-to-bottom by priority
4. The first matching rule determines the redirect URL
5. If no rules match, the default destination URL is used
6. Scan telemetry is logged asynchronously (non-blocking) for analytics

Scan Context Object

The Chameleon Engine builds a rich context object for every scan:

📡 Scan & Redirect Flow

Understanding the lifecycle of a QR code scan:

1. Physical scan → GET /view/[shortId] (API route)
2. QR code lookup in database — checks existence and active status
3. Moderation check — blacklisted or suspended users return a 403 deactivation page
4. Special type handling: hunt progress, loyalty stamps, scratch reveals
5. Scan event logged with full telemetry (device, OS, geo, UTM, bot detection)
6. JSON response returned → client-side page renders the appropriate experience
7. Pixel SDK auto-initializes for post-scan engagement tracking

💳 Subscription Tiers

CirculateQR has four plans. Credits refill monthly: paid-plan credits roll over up to twice the monthly allowance (annual plans too), and the free plan goes back to its allowance on the 1st. The free plan includes no AI credits; AI credit packs can be bought on any plan and never expire. Full details are on the pricing page.

Credit System

Actions consume credits from your monthly balance:

• Static QR code: free
• Dynamic basic QR code: 1 QR credit
• Branded QR (logo + colours): 2 QR credits
• Hosted page: 1 QR credit
• AI art image: 1 AI credit (4 at 4K)
• Google Search grounding: +1 AI credit
• AI Insights report: 2 AI credits
• AI Insights follow-up question: 1 AI credit

⚙️ Settings & Account

Access your account settings at Dashboard → Settings.

Available Settings

• Profile — Update display name, email, and avatar
• API Keys — Generate, rotate, and revoke API keys for programmatic access
• Subscription — View your current tier, usage gauges, and upgrade/downgrade
• Billing — Manage payment method, view invoice history
• Notifications — Configure email alerts for scan milestones and weekly digests
• Creator Hub — Manage marketplace listings, affiliate codes, and payout settings