# gRPC Transport

The `PushwooshGRPC` module provides an optional gRPC transport layer that can improve network performance for communication with Pushwoosh servers. When available, the SDK automatically uses gRPC for supported API methods and falls back to REST if gRPC is unavailable.

<Aside type="note">
Available starting from **SDK version 7.0.18**.
</Aside>

## How it works

By default, the Pushwoosh SDK communicates with servers using REST API over HTTPS. The `PushwooshGRPC` module adds an alternative gRPC transport that offers several advantages:

- **Lower latency** — gRPC uses HTTP/2 with persistent connections
- **Smaller payload size** — Protocol Buffers are more compact than JSON
- **Multiplexing** — Multiple requests can be sent over a single connection

### Automatic fallback

The module includes built-in resilience:

| Scenario | Behavior |
|----------|----------|
| gRPC available | Uses gRPC transport |
| gRPC unavailable | Falls back to REST |
| Network error | Retries with REST |

<Aside type="tip">
You don't need to handle transport selection in your code. The SDK automatically chooses the best available transport.
</Aside>

## Requirements

| Requirement | Version |
|-------------|---------|
| iOS | 13.0+ |
| Xcode | 14.0+ |
| Swift | 5.0+ |

## Installation

### Swift Package Manager

Add `PushwooshGRPC` to your target when integrating the Pushwoosh SDK:

1. In Xcode, go to **File → Add Package Dependencies**
2. Enter the package URL: `https://github.com/Pushwoosh/Pushwoosh-XCFramework`
3. Select `PushwooshGRPC` in addition to the required frameworks

<Tabs>
<TabItem label="Required frameworks">
* `PushwooshFramework`
* `PushwooshCore`
* `PushwooshBridge`
</TabItem>
<TabItem label="Optional frameworks">
* `PushwooshGRPC` — gRPC transport
* `PushwooshKeychain` — Persistent device ID
* `PushwooshLiveActivities` — Live Activities support
* `PushwooshVoIP` — VoIP push notifications
* `PushwooshForegroundPush` — Custom foreground notifications
</TabItem>
</Tabs>

### CocoaPods

Add the gRPC subspec to your `Podfile`:

```ruby
target 'MyApp' do
  use_frameworks!

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshGRPC'
end
```

Then run:

```bash
pod install
```

## Usage

**No code changes required.** Once you add the `PushwooshGRPC` module to your project, it works automatically:

1. On app launch, the SDK detects that gRPC transport is available
2. API calls are routed through gRPC when possible
3. If gRPC fails, the SDK automatically falls back to REST

## Supported methods

The following API methods support gRPC transport:

| Method | gRPC Support |
|--------|--------------|
| Device registration | Yes |
| Tags (set/get) | Yes |
| App open tracking | Yes |
| Push statistics | Yes |

<Aside type="note">
Methods not listed above will continue to use REST transport. The SDK handles this transparently.
</Aside>

## Use cases

The `PushwooshGRPC` module is particularly useful for:

- **High-frequency event tracking** — Reduced overhead for apps that send many events
- **Real-time applications** — Lower latency for time-sensitive operations
- **Bandwidth-constrained environments** — Smaller payload sizes save data

## Troubleshooting

### Verifying the module is active

Check the Xcode console logs when your app launches. You should see a log message like:

```
[Pushwoosh] gRPC transport: ENABLED
```

### Forcing REST transport

If you need to disable gRPC temporarily for debugging, you can remove the `PushwooshGRPC` module from your target. The SDK will automatically use REST transport when gRPC is not available.

<Aside type="caution">
Do not include both gRPC and REST transport code in your app — the SDK handles transport selection automatically based on module availability.
</Aside>