# gRPC 传输
`PushwooshGRPC` 模块提供了一个可选的 gRPC 传输层，可以提高与 Pushwoosh 服务器通信的网络性能。如果可用，SDK 会自动为支持的 API 方法使用 gRPC，并在 gRPC 不可用时回退到 REST。
## 工作原理
默认情况下，Pushwoosh SDK 通过 HTTPS 使用 REST API 与服务器通信。`PushwooshGRPC` 模块增加了一个可选的 gRPC 传输方式，它具有以下几个优点：
- **更低延迟** — gRPC 使用 HTTP/2 和持久连接
- **更小的负载体积** — Protocol Buffers 比 JSON 更紧凑
- **多路复用** — 可以在单个连接上发送多个请求
### 自动回退
该模块内置了弹性机制：
| 场景 | 行为 |
|----------|----------|
| gRPC 可用 | 使用 gRPC 传输 |
| gRPC 不可用 | 回退到 REST |
| 网络错误 | 使用 REST 重试 |
## 要求
| 要求 | 版本 |
|-------------|---------|
| iOS | 13.0+ |
| Xcode | 14.0+ |
| Swift | 5.0+ |
## 安装
### Swift Package Manager
在集成 Pushwoosh SDK 时，将 `PushwooshGRPC` 添加到您的 target 中：
1. 在 Xcode 中，前往 **File → Add Package Dependencies**
2. 输入包 URL：`https://github.com/Pushwoosh/Pushwoosh-XCFramework`
3. 除了必需的框架外，还要选择 `PushwooshGRPC`
* `PushwooshFramework`
* `PushwooshCore`
* `PushwooshBridge`
* `PushwooshGRPC` — gRPC 传输
* `PushwooshKeychain` — 持久化设备 ID
* `PushwooshLiveActivities` — 实时活动支持
* `PushwooshVoIP` — VoIP 推送通知
* `PushwooshForegroundPush` — 自定义前台通知
### CocoaPods
将 gRPC subspec 添加到您的 `Podfile` 中：
```ruby
target 'MyApp' do
use_frameworks!
pod 'PushwooshXCFramework'
pod 'PushwooshXCFramework/PushwooshGRPC'
end
```
然后运行：
```bash
pod install
```
## 使用方法
**无需更改代码。** 将 `PushwooshGRPC` 模块添加到您的项目中后，它会自动工作：
1. 应用启动时，SDK 会检测到 gRPC 传输可用
2. API 调用会尽可能通过 gRPC 路由
3. 如果 gRPC 失败，SDK 会自动回退到 REST
## 支持的方法
以下 API 方法支持 gRPC 传输：
| 方法 | gRPC 支持 |
|--------|--------------|
| 设备注册 | 是 |
| 标签 (设置/获取) | 是 |
| 应用打开跟踪 | 是 |
| 推送统计 | 是 |
## 使用场景
`PushwooshGRPC` 模块在以下场景中特别有用：
- **高频事件跟踪** — 为发送大量事件的应用减少开销
- **实时应用** — 为时间敏感的操作提供更低延迟
- **带宽受限环境** — 更小的负载体积可节省数据流量
## 故障排除
### 验证模块是否已激活
当您的应用启动时，请检查 Xcode 控制台日志。您应该会看到类似以下的日志消息：
```
[Pushwoosh] gRPC transport: ENABLED
```
### 强制使用 REST 传输
如果您需要为了调试而临时禁用 gRPC，可以从您的 target 中移除 `PushwooshGRPC` 模块。当 gRPC 不可用时，SDK 会自动使用 REST 传输。