跳转到主要内容
本页面是示例应用:完整的 OneSignal 集成的一部分,该指南从头到尾跟随一个真实应用。这个应用是 Clean Beans,一款面向合租家庭的打扫值日表应用,使用 Expo(React Native)和 Supabase 后端构建。 Clean Beans 用短信完成两项推送和邮件不擅长的工作:证明电话号码属于输入它的人,以及联系尚未安装应用的人。 两者都发送到原始联系方式,即电话号码或邮箱地址,而不是 External ID。这是它们与本指南中其他所有发送的主要区别。

使用一次性验证码验证电话号码 \

在 User Profile 中,用户可以添加手机号码。应用请求后端发送一个 6 位验证码短信,用户输入后由后端进行检查。只有这样,该号码才算已验证。
电话号码卡片的三种状态:输入号码、输入验证码和已验证

添加电话号码:输入号码、输入验证码、验证完成。

OneSignal 负责投递短信。它不会生成或检查验证码。其余所有工作都由您的后端完成。
1

生成验证码并以哈希形式存储

验证码来自加密安全的随机源。只存储与用户和电话号码绑定的带密钥哈希,因此仅凭数据表无法还原验证码。该密钥是专用密钥 OTP_HASH_SECRET,不作他用。如果未设置该密钥,两个函数都会拒绝运行。
supabase/functions/_shared/otp.ts
supabase/functions/send-otp/index.ts
2

通过 OneSignal 以短信发送

include_phone_numbers 直接定向该号码。如果 OneSignal 从未见过这个号码,会为它创建一个短信订阅。
supabase/functions/send-otp/index.ts
3

检查验证码

后端对用户输入的内容计算哈希,并与存储的哈希进行比较。每次输错都会计数。输错五次后,该验证码失效,必须重新申请。
supabase/functions/verify-otp/index.ts
4

将号码注册为短信订阅

后端确认验证码后,应用会把该号码添加到已登录用户。
src/lib/phone.ts
应用会在每次登录后重复此操作,因此已验证的号码会跟随用户到新设备上。
src/lib/phone.ts
与邮件一样,请在 login() 之后调用 addSms()。向原始电话号码发送会创建一个不属于任何人的订阅。在已登录的应用中调用 addSms() 会把该订阅关联到用户。在此之前,它会在仪表板中显示为一个单独的用户记录。

保护端点 \

按请求发送短信的函数每次运行都会产生费用,也容易被滥用。Clean Beans 采用以下限制。
supabase/functions/send-otp/index.ts
已验证的号码保存在单独的数据表中。只有后端可以写入,因此应用无法将号码标记为已验证,家庭中的其他成员也无法读取它。
supabase/migrations/028_phone_verification_and_invites.sql
仅有电话号码并不代表获得了发送短信的许可。对于验证码,在电话号码字段旁边放置一段说明即可,说明中必须写明发送方、发送内容、可能产生的费用以及如何退订。
src/components/PhoneVerificationCard.tsx

邀请尚未成为用户的人 \

在 Household 界面中,成员可以通过短信或邮件邀请他人。被邀请者没有账户、没有已注册的设备,也没有 External ID。后端直接向原始联系方式发送消息,并附上打开应用加入界面的链接。
邀请对话框及其发送的邀请短信

通过短信或邮件邀请室友,以及对方收到的消息。

同一个端点同时处理两个渠道。短信使用 include_phone_numbers。邮件使用 email_to,并在请求中直接传入主题和 HTML 正文。
supabase/functions/send-invite/index.ts
该链接是在通过普通网页链接打开应用中设置的 Universal Link。有两个细节确保它正常工作:
  • 关闭了邮件点击跟踪。 跟踪会重写链接,使其经过跟踪域名,而重写后的链接无法再直接打开应用。
  • 短信不使用带跟踪的短链接,原因相同。
被邀请者安装应用并登录后,应用的 login() 以及 addEmail() 或 addSms() 调用会把邀请所创建的订阅关联到其新用户上。
被邀请者并未同意接收您应用的消息。关于未经请求的短信和邮件的规定因国家/地区而异,并且可能很严格。Clean Beans 包含此流程是为了演示如何向原始联系方式发送消息,并将每位成员的邀请限制为每天十次。在生产环境中使用此模式之前,请先了解您所发送地区的规定,并考虑让邀请者用自己的手机发送消息。

注意事项 \

  • 必须有发送方。 在 Settings > SMS 中选择默认发送方,或在每个请求中传入 sms_from。两者都没有时,请求会被拒绝,并返回“A valid number is required for ‘From’ field”。
  • 200 响应并不总是意味着消息已发送。 除了状态码,还要检查响应中是否有消息 id。
  • 以 E.164 格式存储号码,即加号后接国家/地区代码和号码,并在调用 API 之前拒绝任何其他格式。
  • OneSignal Verify 是托管的替代方案。 它会为您生成和检查验证码。Clean Beans 自行实现,以展示完整流程。
仪表板设置。 完成短信设置,并选择一个能够覆盖您用户所在国家/地区的默认发送方。

一次性密码

OneSignal Verify 和自行实现。

短信订阅许可和收集

同意和披露要求。

短信 API 参考

所有短信参数。