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

# OneSignal Integration

> Add push notifications to your app with OneSignal

# OneSignal Integration

OneSignal lets you add push notifications to your Newly app. Connect with one click and the AI sets up the SDK, notification components, and a preferences screen for you. Supports both **iOS** and **Android**.

## What is OneSignal?

OneSignal is a push notification platform that handles delivery, user segmentation, engagement tracking, and rich notifications (images, buttons, deep links).

## Setting Up OneSignal

<Steps>
  <Step title="Open &#x22;More&#x22; in Newly and tap Push Notifications">
    Find the Push Notifications panel in the tool strip.
  </Step>

  <Step title="Press Connect OneSignal">
    Newly creates a OneSignal app and links it to your project automatically. No OneSignal account needed.

    <Frame>
      <img src="https://mintcdn.com/natively/u6TkXoiz_IaXxZia/images/onesignal/connect.png?fit=max&auto=format&n=u6TkXoiz_IaXxZia&q=85&s=5e7f00d39f147166e85b4bab929859b1" alt="OneSignal connect panel" width="1908" height="1020" data-path="images/onesignal/connect.png" />
    </Frame>
  </Step>

  <Step title="Configure platform credentials">
    Set up credentials for the platforms you want to support:

    * **iOS**: If you've added Apple credentials in Newly, press **Sync Apple credentials to OneSignal** to configure APNs for iOS push delivery.
    * **Android**: Upload your Firebase service account JSON and `google-services.json` in the Push Notifications panel to enable FCM for Android push delivery. See [Android Configuration](#android-configuration) for details.
  </Step>

  <Step title="Press &#x22;Add push notifications (AI)&#x22;">
    The AI will:

    * Add `NotificationProvider` to your app layout
    * Add a `NotificationBell` component to your home screen
    * Create a notification preferences screen
    * Configure your bundle identifier
  </Step>

  <Step title="Build and test">
    Create a native build and press **Send test notification** to verify everything works.
  </Step>
</Steps>

<Warning>
  Push notifications only work in native builds. They will **not** work in the web preview or Expo Go.
</Warning>

## What Gets Added to Your App

When you connect OneSignal and run the AI setup, three components are added:

| Component                    | Purpose                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| **NotificationProvider**     | Wraps your app layout, initializes the OneSignal SDK, and handles permission prompts |
| **NotificationBell**         | A bell icon for your home screen that shows unread notification count                |
| **Notification Preferences** | A screen where users can manage their notification settings                          |

## Sending Notifications

After setup, you can send notifications by asking the AI to set them up in your app logic. Newly manages the OneSignal connection for you.

<Tabs>
  <Tab title="From Your App">
    Ask the AI to trigger notifications based on events in your app:

    ```
    When a user completes a purchase, send them a
    push notification thanking them for their order.
    ```
  </Tab>

  <Tab title="Segments">
    Target specific user groups:

    ```
    Add a notification that targets users who haven't
    opened the app in 7 days with a re-engagement message.
    ```
  </Tab>

  <Tab title="Test Notification">
    Use the **Send test notification** button in the Push Notifications panel to verify your setup is working.
  </Tab>
</Tabs>

## Common Patterns

<Tabs>
  <Tab title="Welcome Notification">
    ```
    Send a welcome push notification when a new user
    signs up for the first time.
    ```
  </Tab>

  <Tab title="Activity Updates">
    ```
    Notify users when someone comments on their post
    or follows their profile.
    ```
  </Tab>

  <Tab title="Promotional">
    ```
    Set up a notification for a limited-time discount
    that deep links to the offers screen.
    ```
  </Tab>
</Tabs>

## iOS Configuration

iOS requires APNs (Apple Push Notification service) credentials to deliver notifications. You'll need to set up your Apple credentials in Newly first.

<Steps>
  <Step title="Set up Apple credentials">
    Open the **Apple Credentials** panel in Newly. You can either:

    * **Automatic** (recommended): Sign in with your Apple ID and Newly handles the rest
    * **Manual**: Upload your own `.p8` APNs key file from the Apple Developer Portal
  </Step>

  <Step title="Sync to OneSignal">
    In the Push Notifications panel, press **Sync Apple credentials to OneSignal**. This sends your APNs credentials to OneSignal so it can deliver to iOS devices.
  </Step>

  <Step title="Verify">
    The panel will show **APNs credentials detected** when synced successfully.
  </Step>
</Steps>

## Android Configuration

Android requires Firebase Cloud Messaging (FCM) credentials to deliver notifications. You'll need a Firebase project linked to your app.

<Steps>
  <Step title="Create a Firebase project">
    Go to the [Firebase Console](https://console.firebase.google.com) and create a project (or use an existing one). Add an Android app with your app's package name.
  </Step>

  <Step title="Download your credentials">
    You need two files from Firebase:

    * **Service account JSON**: Go to **Project Settings → Service accounts → Generate new private key**. This file lets OneSignal send notifications via FCM.
    * **google-services.json**: Go to **Project Settings → General → Your apps → Download google-services.json**. This file configures your Android app to receive notifications.
  </Step>

  <Step title="Upload to Newly">
    In the Push Notifications panel, find the **Android (FCM)** section and upload both files.
  </Step>

  <Step title="Sync to OneSignal">
    Press **Sync credentials to OneSignal** to send your FCM credentials to OneSignal for Android push delivery.
  </Step>

  <Step title="Verify">
    The panel will show your **Firebase project ID** when configured successfully.
  </Step>
</Steps>

## Testing Notifications

1. Create a **development build** of your app (not Expo Go)
2. Install on a physical device or simulator
3. Accept the push notification permission prompt
4. Go back to the Push Notifications panel in Newly
5. Press **Send test notification**

<Tip>
  If the test notification doesn't arrive, make sure your platform credentials are synced (APNs for iOS, FCM for Android) and that the app has notification permissions enabled on the device.
</Tip>

## Best Practices

<CardGroup cols={2}>
  <Card title="Don't Spam" icon="bell-slash">
    Only send notifications users care about. Too many and they'll uninstall.
  </Card>

  <Card title="Personalize" icon="user">
    Use segments and user data to send relevant messages
  </Card>

  <Card title="Respect Preferences" icon="sliders">
    Let users control which notifications they receive
  </Card>

  <Card title="Time It Right" icon="clock">
    Schedule notifications for when users are most likely to engage
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Notifications not arriving">
    * Make sure you're testing on a **native build**, not Expo Go or web preview
    * Check that the device has notification permissions enabled
    * **iOS**: Verify APNs credentials are synced in the Push Notifications panel
    * **Android**: Verify FCM credentials are uploaded and synced
  </Accordion>

  <Accordion title="APNs not detected">
    * Add your Apple credentials in the Apple Credentials panel first
    * Then press **Sync Apple credentials to OneSignal** in the Push Notifications panel
    * If it still fails, double check your APNs Auth Key, Key ID, and Team ID
  </Accordion>

  <Accordion title="FCM credentials not working">
    * Make sure you uploaded both the **service account JSON** and **google-services.json**
    * Re-download fresh files from the Firebase Console if in doubt
    * Ensure the Firebase project has Cloud Messaging API enabled
  </Accordion>

  <Accordion title="Test notification sent but not received">
    * Make sure the app was opened at least once after installing the native build
    * Check that the user accepted the notification permission prompt
    * **iOS**: Ensure APNs credentials are synced
    * **Android**: Ensure FCM credentials are uploaded and synced
    * Try uninstalling and reinstalling the app, then send again
  </Accordion>

  <Accordion title="Connect button fails">
    * Check your internet connection
    * Try refreshing the page and connecting again
    * If it keeps failing, disconnect and reconnect OneSignal
  </Accordion>

  <Accordion title="Build still uses my old bundle ID after I renamed it">
    Bundle ID changes need two steps. Saving the new bundle ID in Apple Credentials updates your project and `app.json`, but it doesn't automatically push the new value to OneSignal's APNs config. To finish the update:

    1. **More → Push Notifications**, then click **Configure platforms**. This pushes the current bundle ID to OneSignal's APNs platform config.

    Alternatively, you can **Disconnect** OneSignal and **Connect** it again – reconnecting calls Configure platforms automatically.

    See the full walkthrough in [Changing your bundle ID](/guides/bundle-id-changes).
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="OneSignal Docs" icon="book" href="https://documentation.onesignal.com">
    Official OneSignal documentation
  </Card>

  <Card title="Push Notification Guide" icon="bell" href="https://documentation.onesignal.com/docs/push-notification-guide">
    Best practices for push notifications
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Deploy your app with push notifications
  </Card>

  <Card title="RevenueCat" icon="credit-card" href="/integrations/revenuecat">
    Add in-app purchases and subscriptions
  </Card>
</CardGroup>