uniapp-vue3-template 小程序隐私协议授权组件实战:一次接入合规无忧
uniapp-vue3-template 小程序隐私协议授权组件实战:一次接入合规无忧
自从微信小程序对隐私保护提出强制要求后,凡是调用地理位置、相册、用户昵称等隐私接口的应用,都必须向用户弹出隐私协议并完成授权,否则无法通过审核。本文基于 uniapp-vue3-template——一个使用 uni-app + Vite + Vue 3 + TypeScript + uview-plus + UnoCSS 搭建的团队协作快速开发模板,带你实战其内置的 agree-privacy 隐私协议授权组件:一次接入,自动检测、弹框授权、打开隐私政策全套搞定,让小程序合规审核不再卡壳。
为什么你的小程序需要隐私协议授权组件
🔒 从 2023 年起,微信对小程序隐私数据收集行为加强了管控:
- 调用隐私接口(如
wx.getLocation、wx.chooseImage)前,必须让用户明确同意《用户隐私保护指引》 - 未接入授权流程的小程序,不仅接口调用会失败,提审时也会被驳回
- 授权弹框需要用户点击带
agreePrivacyAuthorization能力的"同意"按钮,普通按钮无法完成授权闭环
自己从零实现这一套(检测是否已授权 → 弹出自定义弹框 → 跳转隐私政策 → 监听同意/拒绝事件),往往要踩不少坑。而 uniapp-vue3-template 已经把这一切封装进了一个开箱即用的组件里。
agree-privacy 组件能做什么
核心实现在 src/components/agree-privacy/index.vue,基于 uview-plus 的 u-popup 弹框,主要能力包括:
| 能力 | 说明 |
|---|---|
| 自动检测授权状态 | 组件挂载时调用 wx.getPrivacySetting,判断用户是否已同意 |
| 自动弹框 | 未授权且未禁用自动检测时,自动弹出协议弹框 |
| 一键跳转隐私政策 | 点击"隐私政策"链接,调用 wx.openPrivacyContract 打开官方政策页 |
| 完整授权闭环 | "同意"按钮使用 open-type="agreePrivacyAuthorization",点击即完成微信侧授权 |
| 自定义文案 | 支持自定义标题、副标题与按钮 id |
组件对外暴露了 4 个属性和 4 个事件:
- 属性:
modelValue(v-model 控制显隐)、title/subTitle(自定义文案)、disableCheckPrivacy(是否禁止自动检测弹框)、agreePrivacyId(授权按钮 id,默认agree-btn) - 事件:
agree(用户点击同意并完成授权)、disagree(用户拒绝)、update:modelValue、needPrivacyAuthorization
弹框内容遵循最小必要原则:默认文案清晰告知用户信息收集范围,并提供政策详情入口,符合合规审查对"告知—同意"流程的要求。
三步完成快速接入
得益于模板对 uni-app easycom 机制的配置(见 src/pages.json 与 types/components.d.ts),组件已全局注册,无需 import,直接使用即可。
第一步:在页面中引入组件
以模板首页为例,完整用法参考 src/pages/tab/home/index.vue:
<!-- #ifdef MP-WEIXIN -->
<agree-privacy
v-model="showAgreePrivacy"
:disable-check-privacy="false"
@agree="handleAgree"
/>
<!-- #endif -->
注意两点:
- 隐私授权仅微信小程序需要,使用
#ifdef MP-WEIXIN条件编译,避免 H5、App 端报错 disable-check-privacy="false"表示允许组件自动检测并弹框(默认true为手动模式)
第二步:准备状态与回调
在 <script setup> 中只需一个响应式变量和一个回调函数:
const showAgreePrivacy = ref(false);
function handleAgree() {
// 用户已同意隐私协议,此时可放心调用隐私相关接口
console.log('同意隐私政策');
}
第三步:配置小程序侧并验证
在微信公众平台「设置 → 服务内容声明 → 用户隐私保护指引」中填写需收集的隐私信息并提交,随后在小程序端开启隐私协议相关能力。启动开发版:
pnpm dev:mp-weixin
用微信开发者工具打开 dist/dev/mp-weixin,若当前账号尚未授权,进入首页即会自动弹出隐私协议弹框;点击"隐私政策"可跳转官方政策页,点击"同意"后触发 agree 事件,再次进入页面则不再弹框——至此整个合规闭环验证完成 ✅
核心 API 速查
组件内部主要封装了三个小程序 API,理解它们有助于你按需定制:
wx.getPrivacySetting:获取用户隐私授权状态。res.needAuthorization为true表示需要弹框,同时返回privacyContractName(政策名称)用于展示open-type="agreePrivacyAuthorization":微信特有的按钮能力,用户点击"同意"后由微信完成授权,组件通过@agreeprivacyauthorization事件捕获结果wx.openPrivacyContract:直接打开小程序在平台配置的《用户隐私保护指引》,无需自己维护网页版政策
相关实现集中在 src/components/agree-privacy/index.vue 的 checkPrivacySetting 与 openPrivacyContract 两个方法中,逻辑清晰,方便二次改造。
实战注意事项 ⚠️
- 已授权用户零打扰:
checkPrivacySetting会在已授权时静默跳过弹框,不要手动对老用户重复弹窗 - 按钮 id 别乱改:若不填写
agreePrivacyId,授权按钮 id 必须保持agree-btn;自定义时务必与e.target.id的取值逻辑一致 - 手动弹框场景:把
disableCheckPrivacy设为true,通过v-model在用户点击敏感功能(如"获取定位")时再弹框,体验更贴近"最小必要"原则 - 拒绝后的引导:监听
disagree事件,建议展示功能受限说明而非强制拦截,提升留存 - 仅微信端生效:
wx.*API 在 H5/App 端不可用,条件编译#ifdef MP-WEIXIN不能省略
相关资源
- 组件源码:src/components/agree-privacy/index.vue
- 接入示例(首页):src/pages/tab/home/index.vue
- 全局组件类型声明:types/components.d.ts
- 项目特性说明(含"集成小程序隐私协议授权组件"):README.md
uniapp-vue3-template 作为一套面向团队协作的 uni-app 快速开发模板,除了隐私授权组件外,还内置了 i18n 国际化、Pinia 状态管理、路由拦截登录鉴权、分包预加载、自动化 CI 构建等能力。把这个 agree-privacy 组件搬进你的项目,隐私合规这一审核"拦路虎",一次接入即可安心通过 🚀