# Push campaigns

> Send push notifications to a segment, a list of your users or single devices, from the dashboard or your server, and see what happened to each one.

Source: https://docs.grovs.io/docs/engagement/push-campaigns

A push campaign is one notification sent to an audience you choose. Write it under **Engage › Push** or send it from your server. Grovs delivers it through Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM).

Each campaign has a report: devices targeted, how many Apple and Google accepted, which failed and why, and who tapped.

## How it works

1. **Pick an audience.** A [segment](https://docs.grovs.io/docs/analytics/segments), a list of your user IDs, or a list of devices.
2. **Grovs freezes the audience** at send time, or at release for a scheduled campaign. It finds every device of every person and skips devices that can't get a push.
3. **Grovs delivers from its own servers.** iOS goes to APNs and Android to FCM, with the credentials you uploaded. Large campaigns go out at a steady pace, not all at once.
4. **The SDK reports taps.** On a tap, the SDK records the open and passes the campaign's deep link and data to your app, like any Grovs link.

A tap counts once per device per campaign. It is also recorded as a `push_open` event in your analytics.

## Platforms

| Platform        | Status                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| iOS             | Delivery, tap tracking, deep links and images. Tap tracking and images need iOS SDK 3.1.0 or later.                                                                |
| Android         | Delivery, tap tracking, deep links and images. Tap tracking needs Android SDK 3.1.0 or later. Background pushes are shown by Firebase, foreground ones by the SDK. |
| Flutter         | Tap tracking, deep links and images with plugin 3.2.0. See [Flutter push notifications](https://docs.grovs.io/docs/sdk/flutter/push-notifications).                |
| React Native    | Tap tracking, deep links and iOS images with wrapper 3.1.0. See [React Native push notifications](https://docs.grovs.io/docs/sdk/react-native/push-notifications). |
| Unity           | Tap tracking and deep links with package 1.0.0. See [Unity push notifications](https://docs.grovs.io/docs/sdk/unity/push-notifications).                           |
| Web and desktop | Not reached. Counted as **No channel**.                                                                                                                            |

## Prerequisites

### 1. Upload your push credentials

In the dashboard, go to **Developers › SDK Setup**, **Push Notifications** step.

- **iOS**: upload your APNs `.p8` key with **Upload certificate** and enter the **P8 APN Key ID**. Grovs uses the Apple App Prefix (your Team ID) and bundle ID from the **Register App** step.
- **Android**: upload the **Firebase Service Account JSON Key** and enter the **Firebase Project ID**.

A platform without credentials is skipped. Its devices fail with **Push not configured for this platform**.

### 2. Pass the push token from your app

Register for notifications and give the token to the Grovs SDK. See [Push notifications on iOS](https://docs.grovs.io/docs/sdk/ios/push-notifications) or [Push notifications on Android](https://docs.grovs.io/docs/sdk/android/push-notifications). A device without a token counts as **No channel**.

### 3. Identify your users (optional)

Set the user identifier in the SDK to target people by your own user ID. A push to a user ID reaches every device that user is signed in on.

> **Warning:** The Grovs **test** environment sends through the APNs sandbox, **production** through production APNs. Xcode builds have sandbox tokens, so they only get pushes from the test environment. TestFlight and App Store builds get production pushes.

## Self-hosted

Push campaigns ship in the Enterprise image only. The Community image has no **Push** section.

The Enterprise stack runs an `rpush` process, next to the web app and workers, that holds the APNs and FCM connections. If it isn't running, campaigns stay in **Sending**, devices stay **Queued** and nothing is delivered. See [Configuration](https://docs.grovs.io/docs/self-hosting/configure/configuration) for the Enterprise image.

## Next steps

- [Create a campaign](https://docs.grovs.io/docs/engagement/push-campaigns/create-a-campaign): Write the message, pick the audience and send now, later or in each user's local time.
- [Delivery and reporting](https://docs.grovs.io/docs/engagement/push-campaigns/delivery-and-reporting): What each status and number in the report means.
- [Send from your server](https://docs.grovs.io/docs/engagement/push-campaigns/send-from-your-server): Trigger transactional pushes with your project key.
- [Limits and troubleshooting](https://docs.grovs.io/docs/engagement/push-campaigns/limits-and-troubleshooting): Sizes, rate limits, token handling and common failures.

To send from your server, see the [Server push API reference](https://docs.grovs.io/docs/api-reference/server-push).