v0.1.0 · 开源可用

数字包裹开放平台

一行代码,为你的产品赋予数字内容分发能力。
取件码、即焚、复用、时效 — 开箱即用。

核心能力

为数字商品而生的分发协议

不再局限于传统激活码。数字包裹支持多种分发模式,满足各种业务场景。

🔥

三种分发模式

即焚(perish)— 一次性读取后即销毁;复用(reuse)— 可配置最大使用次数;时效(timed)— 时间窗口内无限次使用。

🔌

一行代码集成

自动初始化脚本开箱即用,一行 <script> 标签即可嵌入你的产品页面,自动显示全屏取件界面。

🔑

RESTful API

完整的 HTTP 接口,支持创建、查询、撤销、验证包裹。CORS 开放,前后端均可调用。

📦

多语言 SDK

TypeScript / JavaScript 全平台支持。Core 核心包、Widget 前端包、Admin 管理包三位一体。

快速开始

1 步完成集成(推荐)

从零到运行,只需一行代码。

一步集成 🚀

只需添加一个 script 标签,SDK 会自动检查缓存、显示全屏取件界面、处理验证逻辑。验证成功后自动隐藏遮罩,放行访问。

html
<script
  src="https://api.virtual-parcel.com/widget/auto-init"
  data-backend="https://api.virtual-parcel.com"
  data-app-id="your-app-id"
  data-cache-key="virtual_parcel_code"
  data-theme="light"
  data-locale="zh-CN"
  data-color="3b82f6"
></script>

✨ 工作原理:

  • SDK 加载后立即执行,检查 localStorage 缓存
  • 无缓存 → 显示全屏 iframe 遮罩(取包裹界面)
  • 用户输入取件码验证 → 成功后缓存并隐藏遮罩
  • 再次访问 → 检查缓存 → 直接放行

💡 配置参数:data-backend 必填,data-cache-key 缓存键名(默认:virtual_parcel_code),data-theme 主题,data-locale 语言,data-color 主色调,data-app-id 应用 ID(多租户隔离,缺省 platform)

⚠️ 接入须知:取件码与「应用」绑定。若你的码是用自己在后台申请的应用密钥创建的(非 platform), 则此处必须加 data-app-id="你的应用ID",否则这些码会提示「取件码不存在」。

传统方式:3 步集成(高级用法)需要更多控制时使用

如果你需要更细粒度的控制(如自定义容器、手动触发显示/隐藏),可以使用传统方式:

html
<!-- 1. 引入 Widget SDK -->
<script src="https://cdn.jsdelivr.net/npm/@openlee/virtual-parcel-widget@latest/dist/index.global.js"></script>

<!-- 2. 准备容器 -->
<div id="widget-container"></div>

<!-- 3. 初始化 -->
<script>
  const widget = new VirtualParcelWidget({
    backendUrl: 'https://your-api.com',
    container: '#widget-container',
    onSuccess: (result) => {
      console.log('取件成功!', result.parcel);
      // 解锁你的内容...
    },
    onFail: (error) => {
      console.log('取件失败', error.message);
    },
  });
  widget.show();
</script>
SDK

三位一体的 SDK 体系

核心验证、前端界面、后台管理 — 各司其职,独立使用。

Core

@openlee/virtual-parcel

核心 SDK — 取件码生成、验证逻辑、存储适配器

pnpm add @openlee/virtual-parcel
Widget

@openlee/virtual-parcel-widget

前端 Widget — 自动初始化脚本 + iframe 取件弹窗

<script src="/widget/auto-init">
Admin

@openlee/virtual-parcel-admin

管理端 SDK — 创建/撤销/查询包裹

pnpm add @openlee/virtual-parcel-admin
API

RESTful API 参考

简洁的 HTTP 接口,JSON 格式,CORS 开放。根据部署方式选择对应的集成路径。

🚀

推荐:自动初始化脚本

最简单的集成方式。只需一行 script 标签,SDK 自动处理所有逻辑:缓存检查、全屏遮罩、验证流程、状态管理。

html
<!-- 公有云 -->
<script src="https://api.virtual-parcel.com/widget/auto-init" data-backend="https://api.virtual-parcel.com"></script>

<!-- 私有云 -->
<script src="https://your-domain.com/widget/auto-init" data-backend="https://your-domain.com"></script>
☁️

公有云集成

直接使用官方托管服务,零运维。前端嵌入自动初始化脚本即可完成集成。

html
<!-- 一步集成:只需这一个 script 标签 -->
<script
  src="https://api.virtual-parcel.com/widget/auto-init"
  data-backend="https://api.virtual-parcel.com"
  data-cache-key="virtual_parcel_code"
  data-theme="light"
  data-locale="zh-CN"
  data-color="3b82f6"
></script>

自动缓存

验证成功后自动缓存,减少重复验证

全屏遮罩

未验证时显示全屏 iframe 阻止访问

零配置

无需编写任何 JavaScript 代码

🏠

私有云集成

将服务部署到你自己的服务器。只需将 backendUrl 改为你的域名即可。

html
<!-- 私有云:一步集成 -->
<script
  src="https://your-domain.com/widget/auto-init"
  data-backend="https://your-domain.com"
  data-cache-key="my_app_code"
></script>

💡 无缝切换:公有云与私有云使用完全相同的 SDK 和 API,只需将 URL 从 https://api.virtual-parcel.com 改为 https://your-domain.com 即可。

集成示例

典型场景

看看其他人怎么用数字包裹。

🎓

知识付费

Course / Content

用户购买课程后,系统生成取件码发送给用户。用户在学习页面输入取件码,即可解锁课程内容。支持即焚模式,阅后即毁。
用户购买生成取件码输入解锁获取内容
🛠️

工具激活

SaaS / Tool

SaaS 工具的高级功能通过取件码解锁。用户购买后获得激活码,输入后工具解锁。支持复用模式,一个码可在多台设备使用。
购买激活获取激活码输入激活功能解锁
🎁

数字礼品

Gift / Voucher

将数字内容打包成礼品,发送取件码给收礼人。收礼人输入码即可领取,如视频课程、会员权益、电子书等。
打包礼品发送取件码收礼人领取内容到手

限时发放

Time-limited

限时开放的数字内容,如限时直播回放、限时优惠链接。使用时效模式,在指定时间窗口内可无限次取件。
创建限时包裹分发取件码窗口期内无限领取

准备好开始了吗?

一行代码,为你的产品赋予数字内容分发能力。

返回首页