微信服务号对接Portal认证系统的OAuth细节

微信扫码登录Portal，是这几年公共WiFi最顺手的认证方式。用户连上WiFi，手机弹出Portal页，扫一下二维码就上线，不用输手机号、不用等验证码。对商场、医院、政务大厅这类流动人群，扫码把认证门槛降到了最低。但真把它跑通，要在公众号配置、OAuth授权、账号绑定几个环节上把细节做对，第一次部署很容易卡。

公众号还是小程序先定清

微信扫码登录有两种载体，公众号网页授权和服务号扫码，或者小程序码。不同载体要求的资质和配置不一样。服务号能做网页授权拿到用户openid，适合Portal这种网页场景；小程序码适合线下物料张贴。项目初期先定清用哪个，再去申请对应资质，别等到设备到了才发现公众号类型不对，重新申请又等一周。

资质之外还有主体一致的问题。Portal系统回调的域名必须和公众号绑定的业务域名一致，且要备案。不少单位公众号主体是总公司，回调域名是分公司，校验过不了。这种坑前期不查，上线当天才爆，很耽误事。建议配置前先把主体、域名、备案三件套对一遍。

OAuth回调的细节

扫码登录走的是OAuth授权码模式。用户扫码，微信带code跳回Portal指定的回调地址，Portal用code换access_token和openid，再据此放行。回调地址必须 HTTPS，且要在公众号后台白名单里。地址写错一个字符，用户扫码后一直转圈进不去。我们处理过的故障里，回调地址漏了结尾斜杠或者带了多余参数，占了不小比例。

openid和实名的对应也要想好。微信openid只是公众号内的用户标识，本身不等同于实名。要做到合规实名，要么走微信实名授权拿到实名信息，要么用户首次扫码时补一个手机号绑定。只拿openid，严格说实名链不完整。不同场所合规强度要求不同，但至少要想清楚这一层，别默认扫码就等于实名了。

扫码失败要有兜底

再顺的扫码，也有用户微信没装、网络差的场景。Portal页上必须留兜底入口，比如短信验证码或者一键获取验证码。扫码是主力不是唯一，兜底断了体验就塌。同时扫码超时、code过期这些异常要有明确提示，别让用户对着一个卡死的二维码干等。

微信扫码登录Portal，体验好是真好，但它是配置密集型方案，资质、域名、回调、兜底四件事都到位才顺。把它当成要前期准备的功能，而不是后台勾一个选项，实施周期和风险都可控得多。

扫码率的隐形指标

微信扫码登录上线后，别只看认证成功没，要看扫码率。多少人连上来扫了码，多少人中途放弃走了兜底。扫码率低不一定是微信不好用，可能是Portal页二维码太小、加载慢、或者兜底入口太显眼把人引走了。这个指标能反推Portal页设计的问题。我们见过扫码率只有四成的场所，把二维码放大、加载提速后直接到七成，体验肉眼可见地变好。

多公众号主体的处理

连锁或者多业态场所，可能不止一个公众号主体，比如总部一个、某品牌一个。Portal要能按场所路由到对应公众号做授权，不能写死一个。否则分店扫出来是别家的码，授权拿不到。多主体场景前期就要在架构上支持公众号配置和场所绑定，别等扩张了才发现只能绑一个。这类扩展性坑，初期不设计，后期改起来伤筋动骨。

二维码本身的设计

扫码体验从二维码那一块就开始。码要够大、对比度够高，手机弱光下能扫；加载要快，别让用户对着转圈。还有一点，二维码对应的链接要稳定，别因为后台改版导致旧码失效。我们见过Portal页改版把回调路径动了，之前贴的物料码全死，现场一片混乱。二维码是用户接触的第一触点，它的稳定性和清晰度，决定了扫码率的下限。

失败要有重试而不是卡死

扫码授权偶尔失败很正常，网络抖一下code就过期。关键是失败后给明确提示和重试入口，而不是停在一个转圈页。用户看到失败原因，才知道是网络问题还是微信问题，决定等还是走兜底。卡死的页面最消磨耐心，重试顺畅的页面用户容忍度高。失败处理设计得好，扫码的整体成功率能拉上来。

扫码数据的回流价值

微信扫码登录产生的数据，不只是认证成功与否。扫码时间分布能看场所客流高峰，放弃率能看Portal页问题，新老用户比例能看复购。这些数据回流给运营，比单纯认证有用得多。很多单位只把扫码当登录手段，数据躺着不用。其实它是一扇观察用户的窗，前提是Portal系统能把这些数据结构化导出，而不是埋在认证日志里翻不出来。

扫码和会员体系打通

微信扫码拿到的openid，是连接会员体系的天然桥梁。用户扫一次码，后台就能把上网身份和会员账号关联，下次不光免登录，还能识别是不是会员、有没有权益。这对商场和连锁尤其值钱，上网行为变成会员洞察的一部分。前提是Portal系统能和会员系统对接，把openid映射到会员ID。打通这一步，扫码就从登录手段升级成运营入口。