推送通知

在 Apple Developer 开启推送

1. 打开 Apple Developer Identifiers
2. 找到与你的 ios.bundleIdentifier 一致的 App ID
3. 进入 App ID
4. 勾选 Push Notifications
5. 点击 Save

模板默认 Bundle ID 是 native.easystarter.dev。如果你已经改成自己的 Bundle ID，请选择自己的 App ID。

配置 APNs Key

先在 Apple Developer 创建 APNs Key：

1. 打开 Apple Developer Keys
2. 点击 + 创建新的 Key
3. 填写 Key 名称，并勾选 Apple Push Notifications service (APNs)
4. 点击 Continue → Register
5. 下载 .p8 文件，并保存页面显示的 Key ID
6. 获取 Apple Team ID：登录 Apple Developer Account，打开 Membership details，复制页面中的 Team ID（由 Apple 分配的 10 位字符串）

.p8 文件只能在 Apple Developer 创建时下载一次，请妥善保存，不要提交到 Git。

方法一：使用 EAS CLI

进入 Native 目录并运行：

cd apps/native
pnpm dlx eas-cli credentials

运行后按下面操作：

1. 选择 iOS
2. 选择要使用的构建环境，例如 development
3. 如果提示登录 Apple Developer，请登录并选择正确的 Team
4. 选择 Push Notifications: Manage your Apple Push Notifications Key
5. 选择 Set up your project to use Push Notifications
6. 如果提示使用已有的 Push Key，请选择 [Add a new push key]
7. 当出现 Generate a new Apple Push Notifications service key? 时选择 No
8. 在 Path to P8 file 中填写刚才下载的 .p8 文件路径
9. 填写凭证信息：
   • Key ID：创建 APNs Key 成功后，复制 Apple Developer 页面显示的 Key ID。如果已经关闭该页面，可以重新打开 Apple Developer Keys，选择刚才创建的 Key 后查看
   • Apple Team ID：前往 Apple Developer Account 获取

完成后，EAS CLI 会将这个 Push Key 配置到当前项目。

方法二：通过 Expo 网页配置

1. 登录 Expo Dashboard
2. 进入 Credentials → Android & iOS credentials → Apple Push Keys
3. 上传 .p8 文件

完成配置后重新构建 iOS App

无论使用方法一还是方法二，配置完成后都需要重新构建 App。将 iPhone 连接到电脑并在手机上选择信任此电脑，然后在项目根目录运行：

pnpm -F native dev:ios-device

按照提示选择你的 iPhone。命令执行完成后，新构建的 App 会自动安装到手机上。

创建 Firebase Android App

1. 打开 Firebase Console

2. 创建或选择一个 Firebase 项目

3. 添加 Android App

4. Package Name 填写 apps/native/app.config.ts 中的 android.package

5. 下载 google-services.json

6. 将文件放到：

   apps/native/google-services.json

7. 在 apps/native/app.config.ts 的 android 配置中添加：

   android: {
     googleServicesFile: "./google-services.json",
   },

创建 FCM V1 凭证

1. 在 Firebase 打开 Project settings → Service accounts

2. 点击 Generate new private key

3. 下载 Service Account JSON 文件

4. 进入 apps/native 并运行：

   pnpm dlx eas-cli credentials

5. 依次选择：

   • Android
   • production
   • Google Service Account
   • Manage your Google Service Account Key for Push Notifications (FCM V1)
   • Upload a new service account key

6. 上传刚才下载的 Service Account JSON

Service Account JSON 包含私钥，不要提交到 Git。

重新生成并构建 Android App

回到项目根目录执行：

pnpm -F native prebuild
pnpm -F native dev:android-device

安装新构建的 App 后再测试通知。

第一步：扩展服务商类型

打开 packages/app-config/src/types.ts，将新服务商追加到 SUPPORTED_NOTIFICATION_PROVIDERS：

export const SUPPORTED_NOTIFICATION_PROVIDERS = ["expo", "onesignal"] as const;

第二步：接入 App 端 SDK

按照服务商提供的 Expo 或 React Native 文档安装 SDK 和 Expo Plugin，并完成 iOS APNs、Android FCM 配置。

然后修改 apps/native/hooks/use-notification-subscription-sync.ts，将 Expo Push Token 替换为新服务商返回的设备推送标识，并将其注册到 Server。

不同服务商的设备推送标识不能混用。切换服务商后，用户需要打开新版本 App，让设备重新注册。

第三步：实现 Provider

在 apps/server/src/notifications/providers/ 下新建服务商文件，并实现 NotificationProvider 接口：

apps/server/src/notifications/providers/onesignal.ts

Provider 需要负责：

• 使用服务商 API 批量发送通知
• 将发送结果转换为成功或失败状态
• 查询并返回通知送达结果
• 设置服务商允许的单次发送和查询数量

可以参考现有的 apps/server/src/notifications/providers/expo.ts。

第四步：注册服务商

打开 apps/server/src/notifications/provider.ts，导入新 Provider，并在 switch 中添加对应分支：

import { createOneSignalNotificationProvider } from "./providers/onesignal";

// Add this branch to the existing switch.
case "onesignal":
  return createOneSignalNotificationProvider({
    appId: env.ONESIGNAL_APP_ID,
    apiKey: env.ONESIGNAL_API_KEY,
  });

同时将服务商需要的密钥写入 Server 环境变量。

第五步：切换配置

打开 packages/app-config/src/app-config.ts，将 notifications.provider 改为新服务商：

notifications: {
  enabled: true,
  provider: "onesignal",
},

然后在项目根目录执行：

pnpm -F native prebuild
pnpm -F native dev:ios-device

Android 真机使用：

pnpm -F native dev:android-device