> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Push Credentials

> Create Firebase and APNs credentials and upload them to the Sendrealm dashboard.

Sendrealm needs provider credentials before it can send mobile push notifications for your app. These credentials prove to Firebase and Apple that Sendrealm is allowed to send notifications for your Android and iOS apps.

There are two separate provider setups:

* Android uses Firebase Cloud Messaging, often called FCM.
* iOS uses Apple Push Notification service, usually called APNs.

You only need the provider that matches the platform you are shipping. If your app ships on both Android and iOS, configure both.

One Sendrealm Push App identity maps to one Android package name and/or one iOS Bundle ID. If you ship separate app identities, such as `com.example.app` and `com.example.app.dev`, configure the provider for the exact identity that will initialize the SDK and receive notifications.

<Warning>
  Firebase service account JSON files and APNs `.p8` files are sensitive production credentials. Upload them only in the Sendrealm dashboard, store backups in a secure secret manager, and rotate them if you suspect exposure.
</Warning>

## What Goes Where

It is easy to confuse the different Firebase and Apple files. Use this table as the quick map:

| Item                                      | Platform | Where it goes               | What it is for                                                          |
| ----------------------------------------- | -------- | --------------------------- | ----------------------------------------------------------------------- |
| Firebase service account JSON private key | Android  | Sendrealm dashboard         | Lets Sendrealm send Android push through FCM.                           |
| Android package name                      | Android  | Sendrealm dashboard and app | Identifies the Android app package Sendrealm accepts for this Push App. |
| `google-services.json`                    | Android  | Your app project            | Required app-side Firebase Android configuration.                       |
| APNs `.p8` private key                    | iOS      | Sendrealm dashboard         | Lets Sendrealm send iOS push through APNs.                              |
| APNs Key ID                               | iOS      | Sendrealm dashboard         | Identifies the Apple private key.                                       |
| Apple Team ID                             | iOS      | Sendrealm dashboard         | Identifies your Apple developer team.                                   |
| iOS Bundle ID                             | iOS      | Sendrealm dashboard and app | Identifies the iOS app topic APNs sends to.                             |

<Note>
  Android apps need `google-services.json` in the app and a Firebase service account private key JSON in Sendrealm. The two files are not interchangeable.
</Note>

## Before You Start

You need:

* A Sendrealm project and app in the dashboard.
* Firebase project owner or admin access for Android setup.
* Apple Developer Account Holder or Admin access for iOS setup.
* Android application ID, for example `com.example.app`.
* iOS bundle ID, for example `com.example.app`.
* A real Android device or Google Play emulator for Android testing.
* A physical iOS device for APNs testing.

## Android: Create The Firebase Key

Use this section for Android push delivery through Firebase Cloud Messaging.

### Step 1: Open The Firebase Project

1. Open the [Firebase console](https://console.firebase.google.com/).
2. Select the Firebase project for your Android app.

Use the same Firebase project that owns the Android app package you ship to users.

### Step 2: If You Start From Google Cloud, Add Firebase First

If your project already exists in Google Cloud but not Firebase, open the Firebase console and choose Add Firebase to Google Cloud project. Select the existing Google Cloud project and complete the Firebase setup.

After Firebase is added, continue with the Android app registration steps below. `google-services.json` is generated from the Firebase Android app registration flow, not directly from the regular Google Cloud console.

### Step 3: Register The Android App

If the Android app is not registered in Firebase yet:

1. From the Firebase project overview, add an Android app.
2. Enter the exact Android package name used by your app.
3. Complete the app registration flow.

The package name is usually your native Android `applicationId`, for example `com.example.app`. It is case-sensitive and must match the app that users install.

### Step 4: Download `google-services.json`

Firebase offers `google-services.json` during Android app setup. Download it and keep it in your app project.

Where the file goes depends on your app type:

| App type          | Where to put `google-services.json`                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Native Android    | `app/google-services.json`                                                                                                      |
| React Native Bare | `android/app/google-services.json`                                                                                              |
| React Native Expo | Save it in the Expo project, then set `android.googleServicesFile` so prebuild copies it to `android/app/google-services.json`. |

Make sure the file name is exactly `google-services.json`. If your browser downloads `google-services (1).json`, rename it before using it.

This file is not enough for Sendrealm server-side push. Continue to the next step to create the private key Sendrealm needs.

### Step 5: Generate The Service Account Private Key

1. In Firebase, open Project settings.
2. Open the Service accounts tab.
3. Click Generate new private key.
4. Confirm the download.
5. Save the downloaded JSON file securely.

This JSON file contains service account credentials. Sendrealm uses it to authorize FCM HTTP v1 send requests.

### Step 6: Upload The Firebase Key To Sendrealm

In Sendrealm:

1. Open your project.
2. Open **Push Notifications** from the project navigation, next to Domains.
3. Choose Android or Firebase provider settings.
4. Upload the Firebase service account JSON file.
5. Enter the Android package name that matches the app Gradle `applicationId`.
6. Save the provider.

After saving, send a test push to an initialized Android device.

## Android Values To Check

Before testing Android push, confirm:

* Firebase project matches the app you ship.
* Android package name in Firebase exactly matches your app `applicationId`.
* Android package name in Sendrealm exactly matches your app `applicationId`.
* Package name casing is identical.
* Firebase service account belongs to the same Firebase project.
* The uploaded file is a full JSON private key file.
* `google-services.json` is present in the Android app.
* The Google Services Gradle plugin is applied for native Android and React Native Bare apps.
* The Android device or emulator has Google Play services.
* The app has initialized the Sendrealm Android or React Native SDK.
* Android 13 and newer devices have notification permission granted.

## Android Common Mistakes

| Mistake                                                          | Result                                                            |
| ---------------------------------------------------------------- | ----------------------------------------------------------------- |
| Uploading `google-services.json` instead of service account JSON | Sendrealm cannot authorize server-side FCM sends.                 |
| Forgetting to add `google-services.json` to the Android app      | The app may not have the Firebase Android configuration it needs. |
| Firebase package name does not match app package name            | Device token registration or delivery can fail.                   |
| Testing on emulator without Google Play services                 | FCM token may never be created.                                   |
| Forgetting Android 13 notification permission                    | Token may register, but notifications may not display.            |
| Using an old deleted service account key                         | Sendrealm send attempts fail authorization.                       |

## iOS: Create The APNs Key

Use this section for iOS push delivery through Apple Push Notification service.

### Step 1: Confirm The App ID And Bundle ID

1. Open [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/).
2. Open Identifiers.
3. Select the App ID for your app.
4. Confirm the Bundle ID matches your Xcode target.

The Bundle ID is the APNs topic Sendrealm sends to. It must match the app that receives the token.

If you do not have an App ID yet, create an explicit App ID with the same Bundle ID used by the app. Do not use a wildcard App ID for push setup.

Where to check the Bundle ID:

| App type          | Where the Bundle ID normally lives                          |
| ----------------- | ----------------------------------------------------------- |
| Native iOS        | Xcode app target, Signing & Capabilities, Bundle Identifier |
| React Native Bare | `ios/<App>.xcworkspace`, app target, Signing & Capabilities |
| React Native Expo | `expo.ios.bundleIdentifier` in Expo config                  |

### Step 2: Enable Push Notifications On The App ID

Apple must allow the Bundle ID to use APNs.

1. In Certificates, Identifiers & Profiles, open Identifiers.
2. Select the App ID for your Bundle ID.
3. Click Edit.
4. Enable Push Notifications.
5. Save and confirm the change.

Apple requires the Account Holder or Admin role to manage App ID capabilities. If you do not see the controls, ask an Apple Developer Account Holder or Admin on your team to do this step.

When an App ID capability changes, provisioning profiles that include that App ID can become invalid. If signing starts failing later, refresh automatic signing, regenerate the provisioning profile, or rebuild through EAS with updated credentials.

### Step 3: Enable Capabilities In The App

The Apple Developer App ID is the server-side permission. The app target also needs the matching entitlement at build time.

For native iOS and React Native Bare:

1. Open the app project or workspace in Xcode.
2. Select the main iOS app target.
3. Open Signing & Capabilities.
4. Add Push Notifications.
5. Confirm the Team and Bundle Identifier match the App ID from Step 1.

For React Native Expo:

1. Confirm `expo.ios.bundleIdentifier` matches the App ID.
2. Configure the Sendrealm Expo plugin.
3. Run `npx expo prebuild --platform ios` or create a new EAS build.
4. If the generated native project is committed, open `ios/*.xcworkspace` and verify the main app target has Push Notifications under Signing & Capabilities.

If your app sends silent pushes or background update notifications, enable background remote notifications:

* Native iOS and React Native Bare: add Background Modes in Xcode and check Remote notifications.
* React Native Expo: set `ios.enableBackgroundRemoteNotifications` to `true` in the Sendrealm Expo plugin, then rebuild.

If your app sends rich image notifications, add a Notification Service Extension:

* Native iOS and React Native Bare: add or configure a Notification Service Extension target.
* React Native Expo: set `ios.notificationServiceExtension` to `true`, run prebuild, and rebuild.

### Step 4: Create The APNs Private Key

1. In Certificates, Identifiers & Profiles, open Keys.
2. Click the add button.
3. Enter a clear key name, for example `Sendrealm Push`.
4. Select Apple Push Notification service.
5. Click Configure next to Apple Push Notification service.
6. Choose the environment configuration and key type.
7. Review the configuration.
8. Click Confirm.
9. Download the private key immediately.

Apple saves the private key as a `.p8` file. You can only download that same private key once. If you lose it, create a new APNs key and update Sendrealm.

The APNs key must have Apple Push Notification service selected. A key created only for another Apple service cannot send notifications through APNs. Apple requires the Account Holder or Admin role to create keys.

### Step 5: Choose Team Scoped Or Topic Specific

Apple may let you choose between Team Scoped and Topic Specific APNs keys.

* Team Scoped is simpler for most teams and can be used across apps owned by the same Apple team.
* Topic Specific restricts the key to selected bundle IDs.

Use Topic Specific if your security policy requires tighter app-level restriction. If you choose Topic Specific, select the exact Bundle ID from Step 1. Use Team Scoped if you want the simplest setup.

### Step 6: Find The APNs Key ID

1. Open Certificates, Identifiers & Profiles.
2. Open Keys.
3. Select the APNs key.
4. Copy the key identifier shown below the key name.

This is the Key ID value required by Sendrealm.

### Step 7: Find The Apple Team ID

Open your Apple Developer account membership details and copy the Team ID for the team that owns the app Bundle ID.

The Team ID must belong to the same Apple developer team that owns:

* The App ID
* The Bundle ID
* The APNs key

### Step 8: Upload APNs Values To Sendrealm

In Sendrealm:

1. Open your project.
2. Open **Push Notifications** from the project navigation, next to Domains.
3. Choose iOS or APNs provider settings.
4. Upload the `.p8` file.
5. Enter the Key ID.
6. Enter the Team ID.
7. Enter the Bundle ID.
8. Select the APNs environment.
9. Save the provider.

After saving, initialize the iOS SDK on a physical device and send a test push.

## APNs Sandbox vs Production

APNs has separate sandbox and production environments. The environment must match the build that created the APNs token.

| Build type                              | APNs environment |
| --------------------------------------- | ---------------- |
| Xcode debug or development-signed build | `sandbox`        |
| Production-signed ad hoc build          | `production`     |
| TestFlight                              | `production`     |
| App Store                               | `production`     |

If the environment is wrong, the app can successfully register a token, but APNs may reject sends for that token.

## iOS Values To Check

Before testing iOS push, confirm:

* Bundle ID in Sendrealm matches the Xcode app target.
* Bundle ID in Sendrealm matches `expo.ios.bundleIdentifier` for Expo apps.
* App ID has Push Notifications enabled in Apple Developer.
* Xcode app target has Push Notifications enabled under Signing & Capabilities.
* Background Modes includes Remote notifications if you send silent/background pushes.
* A Notification Service Extension is present if you send rich image notifications.
* Team ID belongs to the team that owns the Bundle ID.
* Key ID belongs to the uploaded `.p8` key.
* APNs key has Apple Push Notification service enabled.
* Topic Specific APNs key includes this Bundle ID, if you used Topic Specific.
* APNs environment matches the build type.
* The app is running on a physical device.
* The iOS app is installed on a physical device and has completed SDK initialization.
* The user has granted notification permission.

## iOS Common Mistakes

| Mistake                                                  | Result                                                                            |
| -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Using `sandbox` for TestFlight                           | APNs rejects production tokens.                                                   |
| Using `production` for Xcode debug builds                | APNs rejects sandbox tokens.                                                      |
| Wrong Bundle ID                                          | APNs sends to the wrong topic and delivery fails.                                 |
| Wrong Team ID                                            | Provider authentication fails.                                                    |
| Push Notifications not enabled on the App ID             | The app may not receive the proper push entitlement.                              |
| Push Notifications not enabled in Xcode                  | The built app is missing the push notification entitlement.                       |
| Provisioning profile not refreshed after enabling push   | Signing can fail or the app can be built without the expected entitlement.        |
| APNs key created without Apple Push Notification service | Sendrealm cannot authenticate APNs sends with that key.                           |
| Topic Specific key does not include the Bundle ID        | APNs sends for that app are not authorized by the key.                            |
| Missing Background Modes, Remote notifications           | Silent/background pushes may not be delivered to the app for background handling. |
| Missing Notification Service Extension                   | Rich images cannot be downloaded and attached before display.                     |
| Losing the `.p8` file                                    | You must create a new key and update Sendrealm.                                   |
| Testing on simulator                                     | End-to-end APNs testing is unreliable. Use a physical device.                     |

## Upload In Sendrealm

The exact dashboard labels may vary, but the provider setup follows this shape:

1. Open your Sendrealm project.
2. Open **Push Notifications** from the project navigation, next to Domains.
3. Add or edit the Android provider.
4. Upload the Firebase service account JSON and enter the Android package name.
5. Add or edit the iOS provider.
6. Upload the APNs `.p8` file and enter Key ID, Team ID, iOS Bundle ID, and environment.
7. Save the provider settings.
8. Send a test notification to a development device.

If Sendrealm shows validation errors, check that the files were not renamed into unsupported formats and that pasted IDs do not include extra spaces.

## Test The Full Flow

Credentials are only one half of push setup. The app must also register a token.

For Android:

1. Install the app on a Google Play device or emulator.
2. Initialize the Android or React Native SDK.
3. Request notification permission on Android 13 or newer.
4. Confirm diagnostics show token presence.
5. Send a test push from Sendrealm.

For iOS:

1. Install the app on a physical device.
2. Initialize the iOS or React Native SDK.
3. Request notification permission.
4. Confirm diagnostics show token presence.
5. Send a test push from Sendrealm.

## Delivery Timing Is Best Effort

Credentials let Sendrealm authenticate with Firebase and APNs. They do not guarantee that every notification appears instantly on every device.

After Sendrealm sends a push, final delivery is still affected by:

* Device network connectivity.
* Android Doze and App Standby.
* Android battery optimization and manufacturer-specific background restrictions.
* Android notification channel settings.
* FCM priority and throttling behavior.
* iOS APNs priority.
* iOS Focus, notification summary, and notification settings.
* iOS background update throttling.
* Stale or inactive device tokens.

This means a valid setup can still produce notifications that are delayed, dropped, throttled, collapsed, or hidden by user settings. Test on real devices, check SDK diagnostics, and make sure the app can fetch important state when it opens.

## Rotate Credentials

Rotate provider credentials when a key is exposed, when team access changes, or as part of your security policy.

For Firebase:

1. Generate a new service account private key.
2. Upload the new JSON file to Sendrealm.
3. Send a test push.
4. Delete the old service account key in Google Cloud or Firebase once the new key works.

For APNs:

1. Create and download a new APNs key.
2. Upload the new `.p8`, Key ID, Team ID, Bundle ID, and environment to Sendrealm.
3. Send a test push.
4. Revoke the old APNs key after traffic has moved to the new key.

Do not revoke the old key before confirming the new key works, unless the old key is actively compromised and must be disabled immediately.

## Security Notes

* Never commit Firebase service account private keys.
* Never commit APNs `.p8` files.
* Do not send provider private keys through chat, email, or tickets unless your company has an approved secure process.
* Limit dashboard access to people who need to manage push providers.
* Rotate credentials after employee offboarding if your policy requires it.
* Keep a record of which Firebase project and Apple team belong to each Sendrealm app.

## Official References

* [Firebase Admin SDK service account setup](https://firebase.google.com/docs/admin/setup)
* [Firebase Android app setup](https://firebase.google.com/docs/android/setup)
* [FCM HTTP v1 authorization](https://firebase.google.com/docs/cloud-messaging/send/v1-api#authorize-http-v1-send-requests)
* [Apple APNs authentication tokens](https://developer.apple.com/help/account/capabilities/communicate-with-apns-using-authentication-tokens)
* [Create an Apple private key](https://developer.apple.com/help/account/keys/create-a-private-key)
* [Get an Apple key identifier](https://developer.apple.com/help/account/keys/get-a-key-identifier)

## Related Pages

* [Android SDK](/sdks/android)
* [iOS SDK](/sdks/ios)
* [React Native Expo SDK](/sdks/react-native-expo)