🚦Push Notifications - OneSignal

Natively uses the OneSignal service to provide robust Push Notification support inside your mobile application. Notifications can deliver timely and important information to your users, whether their device is locked or actively in use.

We do not currently support Rich Push Notifications (notifications containing action buttons or images). This feature will be added soon.

Prerequisites

Android Configuration

To send push notifications to Android devices through the Google Play Store, OneSignal requires Firebase Cloud Messaging (FCM) credentials.

Requirements:

• A Firebase account (free)

Create or open your Firebase Project

Go to the Firebase console.

• If you don’t have a project yet, click Add project and complete the setup.

• If you already have a project, select it.

Enable Firebase Cloud Messaging API v1

• In Firebase, click the gear icon next to Project Overview > Project settings.

• If Firebase Cloud Messaging API (V1) is disabled, click the 3-dot menu > Open in Cloud Console.

• In the Google Cloud Console, click Enable. Wait a few minutes for the change to reflect in Firebase.

Generate a Service Account JSON file

• Return to Project Settings > Service Accounts

• At the bottom, click Generate new private key.

• Confirm by clicking Generate key in the popup.

Required Service Account permissions:

• cloudmessaging.messages.create

• firebase.projects.get

These are included by default. If you’re using a custom Service Account, ensure it has:

• roles/firebasemessaging.admin

• roles/firebase.viewer

• Save the .json file in a secure location. You will need it shortly.

iOS Configuration

OneSignal configuration

Requirements:

• A OneSignal account (free)

Create App

• Navigate to your OneSginal dashboard

• Click New App/Website

• Enter your application's name in the OneSignal App Name field.

• Select the option to create a new organization and enter its name.

• Choose either the Apple iOS (APNs) or Google Android (FCM) channel.

• Click Next.

If you have both an iOS and Android app for one website, you only need one OneSignal application with both platforms enabled.

You can set up an additional platform later by navigating to Settings > Push & In-App.

Android Configuration

• Upload the .json file under Service Account JSON by clicking Select file.

• Click Save & Continue.

• Select the SDK: Android Native

• Click Save & Continue.

• Copy your App ID and click Done.

iOS Configuration

Natively Dashboard Setup

Once OneSignal is set up, you must link it to your Natively app.

• Navigate to Features > Notifications > OneSignal in your app's dashboard.

Optionally: Enable the "Automatically request push permission on app launch" checkbox to automatically trigger the system permission prompt immediately after the user launches the app.

Requirement: Enter a clear description explaining to the user exactly why your app needs push permission to avoid app rejection.

• Enable OneSignal Notifications and enter the App ID from your OneSignal account.

• Click Save.

You must rebuild your application for these changes to take effect.

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code) or JavaScript SDK (Code).

Initialization

Bubble.io Plugin

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.

2. Check Installed Plugins: Look through your list of installed plugins for "Natively iOS & Android app builder".

   • If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

• If it is NOT installed: Click the + Add plugins button , search for "Natively", and click Install.

JavaScript SDK

Setup logic

Bubble.io Plugin

Drag the Natively - Banner element onto your page.

This element must be set to Visible on page load to initialize correctly. It should be placed directly on the page root and not inside hidden containers, such as Popups, Floating Groups, Group Focus elements, or Repeating Groups. To hide the element from your UI, you may set its dimensions to 0x0 px.

Element Logic (Events, States, & Actions)

Use the following data points to build your ad logic.

• Events:

  • OneSignal Player ID Updated: Fires whenever the Player ID is successfully retrieved or from OneSignal.

  • Permissions Authorized: Triggered when the user taps Allow on the native system permission dialog.

  • Permissions Denied: Triggered when the user taps Don't Allow on the native system permission dialog.

  • Permission Status Updated: Fires whenever the device's notification settings change.

  • External ID Updated: Triggered after an External ID is successfully set, updated, or removed.

  • External ID Error: Fires if an operation involving an External ID fails.

• States:

  • Permission Status (Yes/No): Returns Yes if the user has granted notification permissions.

  • OneSignal PlayerId (Text): The unique identifier for the current device, used to target this specific user.

  • OneSignal ExternalId (Text): The unique identifier for the current user, used to target this specific user.

  • Error message (Text): Returns the text of the error encountered during a failed operation. This state is updated if an action (such as an Set the user's External ID) fails.

The OneSignal Player ID is equivalent to the Subscription ID. You can locate this value within your OneSignal dashboard by navigating to Audience → Subscriptions.

• Actions:

  • Request the user's push notification permission: Triggers the native system dialog using the "Permission description" defined in your dashboard. Open Settings: If permission was previously denied, this displays a native alert offering to take the user directly to the system settings to enable notifications.

  • Get the user's OneSignal PlayerId: Manually refreshes the OneSignal Player ID state. Useful if you need to ensure the ID is current before a specific workflow.

  • Get the user's push notification permission status: Re-checks the device's notification settings and updates the Permission Status state (Yes/No).

  • Get the user's External ID: Fetches the custom ID currently associated with this Player ID in OneSignal.

  • Set the user's External ID: Links a custom ID to this OneSignal Player ID.

  • Remove the user's External ID: Unlinks the custom ID from the current Player ID.

JavaScript SDK

How to use

While you can trigger push notifications directly from the client side for rapid testing within the Natively Preview app, we strongly recommend migrating all production logic to Backend Workflows (server side).

If a user grants permission during their current session, the updated status will be reflected in OneSignal on the subsequent (second) app launch.

Implementation Best Practices

Avoid overwhelming users with a permission prompt the moment the app opens. Instead, request push notification access at a "high-value" moment in the user journey - such as during onboarding or immediately after a user opts into a feature that requires alerts (e.g., "Notify me when my order ships").

To ensure your users receive notifications reliably across all their devices, follow this login synchronization flow:

• Verify Player ID on Login: Every time a user authenticates, retrieve their current device's Player ID. Compare this against the ID stored in your database for that user.

• Register New Devices: If the current Player ID is not found in your database, the user is likely on a new device. Use this opportunity to request push permissions and register the device.

• Sync via External ID: Once the device is registered, call Set External ID using your internal User ID. This informs OneSignal that this device belongs to your specific user.

• Maintain Your Database: Always save the latest Player ID to your user record. It's possible storing these as a list to support users with multiple active devices (e.g., iPhone and iPad).

• Send Notifications: Use your stored Player IDs or External IDs to trigger targeted push notifications via backend workflows.

Bubble Plugin

To authorize push notifications from your Bubble workflows, navigate to the Plugin Settings tab and enter your OneSignal REST API Key into the onesignal_apiKey field and the App ID into the onesignal_appId field.

Detailed instructions on creating and managing your API keys can be found in the OneSignal Documentation.

Requesting Permissions

Trigger the permission request when a user explicitly opts in to receive notifications (e.g., flipping a "Enable Notifications" toggle).

• Existing Permissions: If the user has already granted access, the system popup will not reappear. Instead, the element will silently refresh the OneSignal PlayerId state.

• Handling Denials (Open Settings): If the Open Settings option is enabled and the user previously denied permissions, a dialog will appear. This prompt invites the user to navigate to their device settings to manually re-enable notifications for your app.

Capturing the Player ID

To send targeted notifications, you must map the device's unique identifier to your user records.

• Create a workflow for the event Notification permission authorized. Within this workflow, trigger the action Get the user's OneSignal Player Id. This ensures that as soon as a user grants access, the app actively fetches their new identifier.

• Listen for the OneSignal Player Id updated event. This event fires automatically once the identifier is successfully received from the OneSignal servers.

• Within the "Updated" event workflow, save the OneSignal Player Id state's value to the Current User in your database.

Think of the Player ID as the "digital address" for the device. Without saving this address to your database, your backend workflows will not know where to deliver the notification.

Sending a Notification

In this scenario, we will schedule an automated push notification to be sent three days after a customer orders a product, informing them that their order is on its way.

1. The Trigger (Client-Side) When a customer completes a purchase (e.g., new_order_placed), trigger a Backend Workflow to run with a 3-day delay. You must pass the user's Player ID and the Order Details to this backend workflow.

2. The Execution (Backend Workflow) Create a backend workflow (e.g., send_delivery_update) that uses the OneSignal - User Single PlayerId - Send Push action.

Configure the following parameters:

• Player ID: The unique identifier retrieved from your database.

• Title & Message: "Your order is on its way!"

• Redirect URL: The specific internal page link (e.g., https://example.com/orders/123) that the app will open when the user taps the notification. This parameter is optional. If not provided, the app will open the App URL.

3. The Result: Deep Linking When the user receives and taps the notification, the app intercepts the Redirect URL and automatically opens that specific page within the app, rather than just the home screen.

Using OneSignal Templates

If you have pre-defined layouts in your OneSignal dashboard, you can trigger them by providing a Template ID.

• The Override Rule: When a Template ID is provided, it takes precedence over the Title, Subtitle, Message, and Redirect URL fields. Any content entered into those individual fields will be ignored in favor of the template's settings.

• Setup: Simply paste your Template ID (found in the OneSignal Dashboard under Messages → Templates) into the designated field in the OneSignal - User Single PlayerId - Send Push action.

Targeting by OneSignal Segments

Use segments to broadcast messages to specific groups of users based on their behavior, location, or custom tags. Use the OneSignal - Segments - Send Push action in your backend workflows to reach large audiences simultaneously.

• Included Segments: Enter the exact names of the segments you wish to target (e.g., Active Users or Free Tier). To reach your entire audience, use the default OneSignal segment name: Total Subscriptions.

• Excluded Segments: (Optional) Specify segments that should not receive the notification. For example, you can target All Users but exclude Premium Subscribers to send a specific upgrade promotion.

• Important: Segment names must match the spelling and capitalization used in your OneSignal dashboard exactly.

Other Options

Custom Sound

Be sure to create sound files according to the following rules. If the device cannot find the file in question, or if the file is not in a supported format, it will fall back to the default system notification sound.

• Filename must be natively.wav.

• Recommended length less than 30 seconds. Keep file size small, large files may not play on some devices.

Natively Dashboard Configuration

• In your Natively dashboard, navigate to Features → Notifications → OneSignal.

• Locate the Custom Notification Sound section and click Click to upload file.

• Upload your audio file.

• Rebuild your app to apply changes.

Android Configuration

• In your OneSignal Dashboard, go to Settings → Push & In-App Settings → Android Notification Channels.

• Click Add Group.

• Name the new group and click Submit.

• Set the Sound field to exactly natively.

  • Set Importance to Urgent or High (required for the sound to trigger).

• Create the channel and copy the generated Channel ID.

• Paste this ID into your Bubble Plugin or OneSignal API payload.

Because Android "locks" channel settings, you must reinstall your app on your device for the new sound settings to take effect.

iOS Configuration

Troubleshooting

If your notifications are not appearing as expected, follow this tiered checklist to identify and resolve the issue.

Essential Configuration

• App Rebuild Required: Any changes made to the configuration in the Natively Dashboard require a new build of your application to take effect.

• The "Preview" Tag: If you are testing using the Natively Preview App, you must set the tag to preview in your Bubble plugin settings.

  • For your own build, this field must be left blank.

• Natively Dashboard: Verify that the OneSignal feature is toggled ON and that your OneSignal App ID is pasted correctly.

Delivery & Targeting

• Player ID Validation: Ensure you are targeting the correct Player ID (Subscription ID). Check your OneSignal Dashboard → Audience to verify the device is active.

• Bubble Workflow Logic: Double-check that your "Send Push" action is actually firing. Use the Bubble Debugger to confirm that the Player ID is not empty at the moment the action runs.

• Network Connectivity: Confirm the test device is on a stable internet connection. Some corporate firewalls or VPNs may block the ports used by APNs (Apple) or FCM (Google).

Platform-Specific Fixes

• iOS: Certificate Refresh: If iOS notifications fail while Android works, your Push Certificate may have expired or been misconfigured. Try re-generating your .p8 or .p12 certificate in the Apple Developer Portal and re-uploading it to OneSignal.

• Android: The Reinstall Rule: During development, Android "locks" notification channels upon the first launch. If you have changed the sound or category settings, you must uninstall and reinstall the app to force the OS to register the new configuration.

  • Note: This behavior is only for development/testing and does not affect users once the app is live in the Play Store.

Device-Level Obstacles

• App Permissions: Verify that the user has actually granted permission. Check the system settings on the device: Settings → [Your App] → Notifications.

• Focus Modes: Ensure the device is not in Do Not Disturb or a specific Focus Mode (Work, Sleep, etc.).

• Low Power Mode: Some devices disable background data and push synchronization when Low Power Mode is active to conserve battery.