Appqr

---

你开发了一款应用，并已上架两个应用商店。你需要一个二维码，用于落地页、名片和媒体资料包。其他工具都会为此收取月度订阅费。AppQR 免费、可在本机运行，并且永远可用。

npx appqr setup \
  --ios "https://apps.apple.com/app/id123456789" \
  --android "https://play.google.com/store/apps/details?id=com.myapp" \
  --url "https://myapp.com/go"

✓ redirect.html  →  ./appqr-output/redirect.html
✓ qr.png         →  ./appqr-output/qr.png

→ Upload redirect.html to your site at: https://myapp.com/go
→ Done! For future campaigns, run: appqr campaign

---

工作原理

Scan QR
  ↓
Phone opens: myapp.com/go?d=eyJpb3MiOiJodHRw...
  ↓
redirect.html detects device (client-side JS, no server)
  ↓
iOS user  → App Store
Android   → Google Play

二维码会将两个应用商店的网址以 base64 编码的形式写入网址本身。redirect.html 是一个很小的通用文件，负责解码并重定向——其中不包含任何活动数据，也永远不需要更改。每个新活动只需生成一张新的二维码图片。

重定向链中绝不会经过 AppQR 服务器。 一切都在开发者自己的网站上运行。

---

安装

npm install -g appqr

或者无需安装即可运行：

npx appqr setup ...

---

使用方法

步骤 1 — 设置（每款应用仅需一次）

appqr setup \
  --ios "https://apps.apple.com/app/id123456789" \
  --android "https://play.google.com/store/apps/details?id=com.myapp" \
  --url "https://myapp.com/go"

在你的第一个二维码中启用活动跟踪：

appqr setup \
  --ios "https://apps.apple.com/app/id123456789" \
  --android "https://play.google.com/store/apps/details?id=com.myapp" \
  --url "https://myapp.com/go" \
  --ios-params "ct=launch&pt=12345&mt=8" \
  --android-params "utm_source=launch&utm_campaign=v1&utm_medium=organic" \
  --output ./public/go

将 redirect.html 上传到你的网站。这是你唯一需要上传的文件。之后再也不必动它。

---

步骤 2 — 创建新活动二维码（次数不限）

appqr campaign \
  --ios "https://apps.apple.com/app/id123456789" \
  --android "https://play.google.com/store/apps/details?id=com.myapp" \
  --url "https://myapp.com/go" \
  --ios-params "ct=instagram_launch&pt=12345&mt=8" \
  --android-params "utm_source=instagram&utm_campaign=launch&utm_medium=paid" \
  --output ./qrs/instagram

✓ qr.png  →  ./qrs/instagram/qr.png

iOS URL:     https://apps.apple.com/app/id123456789?ct=instagram_launch&pt=12345&mt=8
Android URL: https://play.google.com/store/apps/details?id=com.myapp&utm_source=instagram...

No file upload needed — redirect.html already handles this.

无需上传，无需更改网站。每个活动只需生成一张新的二维码图片。

---

显示活动参数格式

appqr params

---

用作 Node.js 包

import { setup, campaign } from 'appqr'

// First time setup
const result = await setup({
  ios: 'https://apps.apple.com/app/id123456789',
  android: 'https://play.google.com/store/apps/details?id=com.myapp',
  hostedUrl: 'https://myapp.com/go',
  iosParams: 'ct=launch&pt=12345&mt=8',
  androidParams: 'utm_source=launch&utm_campaign=v1&utm_medium=organic',
  outputPath: './public/go'
})
// → result.redirectPath  upload this once
// → result.qrPath        use this as your QR image

// Campaign QR — no upload needed
const qr = await campaign({
  ios: 'https://apps.apple.com/app/id123456789',
  android: 'https://play.google.com/store/apps/details?id=com.myapp',
  hostedUrl: 'https://myapp.com/go',
  iosParams: 'ct=instagram_launch&pt=12345&mt=8',
  androidParams: 'utm_source=instagram&utm_campaign=launch&utm_medium=paid',
  outputPath: './qrs/instagram'
})
// → qr.qrPath  your campaign QR image

内含完整的 TypeScript 类型定义。无需安装 @types/appqr。

---

MCP — 供 AI Agent 使用（Claude、Cursor、Copilot）

AppQR 内置了 MCP（Model Context Protocol）服务。支持 MCP 的 AI Agent 可以直接生成智能二维码，无需了解命令行，也无需手动操作。

添加到 Claude Desktop

{
  "mcpServers": {
    "appqr": {
      "command": "npx",
      "args": ["appqr", "mcp"]
    }
  }
}

添加到 Cursor

{
  "mcpServers": {
    "appqr": {
      "command": "npx",
      "args": ["appqr", "mcp"]
    }
  }
}

连接后，Agent 可以：

“为我的应用生成智能二维码。App Store：https://apps.apple.com/app/id123。Play Store：https://play.google.com/store/apps/details?id=com.app。托管地址为 myapp.com/go。”

Agent 会直接调用 appqr_setup 或 appqr_campaign，并返回文件路径。

提供的 MCP 工具

工具	说明
appqr_setup	首次设置——生成 redirect.html 和 qr.png
appqr_campaign	新活动二维码——仅生成 qr.png
appqr_validate	生成前验证应用商店网址

---

活动参数格式

Apple App Store

参数	含义	必填	示例
ct	活动标记——你的标签	建议填写	ct=instagram_launch
pt	提供商标记——你的 Apple 数字 ID	建议填写	pt=12345
mt	媒体类型——应用固定为 8	是	mt=8

--ios-params "ct=instagram_launch&pt=12345&mt=8"

Google Play（标准 UTM）

参数	含义	必填	示例
utm_source	流量来源	是	utm_source=instagram
utm_medium	营销媒介	是	utm_medium=paid
utm_campaign	活动名称	是	utm_campaign=launch
utm_content	特定广告或创意素材	否	utm_content=banner_v1
utm_term	搜索广告关键词	否	utm_term=todo+app

--android-params "utm_source=instagram&utm_campaign=launch&utm_medium=paid"

---

为什么不直接用 Bitly / QR Tiger / Branch？

	其他工具	AppQR
iOS/Android 智能重定向	✓ 付费	✓ 免费
价格	$15–40/月	免费
对方停止服务后，你的二维码仍可用	✗	✓ 永远可用
活动跟踪参数	✓ 付费	✓ 免费
分别设置 Apple 和 Google 参数	✗ 很少支持	✓ 支持
适合 Agent / 命令行	✗	✓ 支持
MCP 服务	✗	✓ 支持
你的活动数据存储在对方服务器上	✓ 始终如此	✗ 从不如此

---

仓库结构

appqr/
├── public/
│   ├── index.html        # Landing page
│   └── llms.txt          # AI agent discovery
├── api/
│   └── ping.js           # Telemetry (Vercel serverless)
├── cli/
│   ├── bin/appqr.js      # CLI entry point
│   ├── src/
│   │   ├── core.js       # Core logic
│   │   ├── mcp.mjs       # MCP server
│   │   ├── telemetry.js  # Anonymous counters
│   │   ├── index.js      # npm package exports
│   │   └── index.d.ts    # TypeScript types
│   └── package.json
├── vercel.json
└── README.md             # This file

---

部署 Web 后端（Vercel + Supabase）

Web 后端托管着落地页，并收集匿名使用遥测数据（安装次数、使用次数、Agent 与人工使用的比例——不包含个人数据）。

1. 部署到 Vercel

git clone https://github.com/harishakumarn/appqr
cd appqr
vercel deploy

也可以通过 Vercel 控制面板连接——导入仓库，一键部署。

2. 设置 Supabase（可选——用于遥测）

在 Supabase 项目中运行以下 SQL：

create table counters (
  id integer primary key default 1,
  installs bigint default 0,
  setups bigint default 0,
  human_runs bigint default 0,
  agent_runs bigint default 0,
  qrs_generated bigint default 0,
  constraint single_row check (id = 1)
);

insert into counters (id) values (1);

create or replace function increment_counter(col_name text)
returns void as $$
begin
  execute format(
    'update counters set %I = %I + 1 where id = 1',
    col_name, col_name
  );
end;
$$ language plpgsql;

将以下内容添加到 Vercel 环境变量中：

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key

3. 更新遥测 URL

在 cli/src/telemetry.js 中，将 TELEMETRY_URL 替换为你的 Vercel 部署 URL。

4. 发布到 npm

cd cli
npm publish

---

隐私与遥测

AppQR 每次运行时会发送一次匿名 ping。绝不会收集 URL、营销活动数据、商店链接、个人信息或设备标识符。

唯一追踪的数据是以下某一项的计数增量： installed、setup、human_run、agent_run、qr_generated

永久选择退出：

echo 'export APPQR_NO_TELEMETRY=1' >> ~/.zshrc

或按次选择退出：

APPQR_NO_TELEMETRY=1 appqr setup ...

---

贡献

欢迎提交 PR。代码库刻意保持精简——核心逻辑不到 200 行。

git clone https://github.com/harishakumarn/appqr
cd appqr/cli
npm install
node bin/appqr.js setup --help

---

许可证

MIT © AppQR Contributors