📲OneSignal - Push Notifications

Reach your users with timely push notifications, powered by OneSignal.

What are OneSignal Push Notifications?

Natively provides built-in support for OneSignal to handle push notification delivery for your app. OneSignal manages device registration and targeting through its own dashboard, and you send notifications either directly from the OneSignal dashboard or via the OneSignal REST API.

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

Prerequisites

This feature requires the Unlimited or Lifetime plan. See all plans

A OneSignal account.
iOS:
- An Apple Developer account.
- Your iOS app is already published in the Natively Dashboard.
Android:
- A Firebase account.
- Your Android app is already published in the Natively Dashboard.

OneSignal Configuration

Pre-OneSignal Configuration

To send push notifications to Android devices, OneSignal requires Firebase Cloud Messaging (FCM) credentials.

Create or open your Firebase Project

Go to the Firebase console.
If you don’t have a project yet, click Create a project and complete the setup.
If you already have a project, select it.

Confirm Firebase Cloud Messaging API v1 is enabled

While in the Project Overview page, select Settings > General from the left sidebar, then go to the Cloud Messaging tab.

Firebase Cloud Messaging API (V1) is enabled by default for most projects.

If it shows as disabled:

Click on the 3-dots menu.
Click Manage the API in Google Cloud Console.
Click Enable in the Google Cloud Console. Wait a few minutes for the change to reflect in Firebase.

Generate a Service Account JSON file

While on the Project Overview page, select Settings > General from the left sidebar, then go to the Service Accounts tab:

At the bottom, click Generate new private key.
Confirm by clicking Generate key in the popup.
Save the .json file in a secure location.

You'll need it for OneSignal Dashboard Configuration.

To send push notifications to iOS devices, OneSignal requires the Push Notifications App Capability enabled on your Bundle ID and an APNs authentication key from your Apple Developer account.

App Capabilities Configuration

App capabilities define what system-level features your app is allowed to use on iOS. Before Natively can include the OneSignal Push Notifications feature in your build, the Push Notifications capability must be explicitly enabled in your Apple Developer account for your app's Bundle ID.

Open your Apple Developer account and navigate to Certificates, IDs & Profiles > Identifiers.
Select your app's Bundle ID.
Scroll down the Capabilities list and enable Push Notifications.
Click Save and confirm.

Set up APNs Authentication Key

Open your Apple Developer account and navigate to Certificates, IDs & Profiles > Keys.
Click + to register a new key.
Enter Key Name.
Select the Apple Push Notifications service (APNs) checkbox and click Configure.
In the Environment dropdown menu, select Sandbox & Production and click Save.
Click Continue, then Register.
Download the generated .p8 key.

You can only download this file once, so save it securely. If you lose it, you'll need to revoke the key and generate a new one.

Gather your credentials

Collect:

Key ID - located in the row of the key you just created. Make sure it matches the downloaded .p8 file.
Team ID - located in your Apple Developer account under Membership details.
Bundle ID - located in your Natively Dashboard under Publish > iOS Build > Bundle Identifier.

You'll need these for OneSignal Dashboard Configuration.

OneSignal Dashboard Configuration

Create OneSignal App

Navigate to your OneSignal dashboard and 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 add the second platform later in your OneSignal app dashboard under Settings > Push & In-App.

Configure your platform

Click Select file under Service Account JSON and upload the .json file you downloaded in the Generate a Service Account JSON file step above.
Click Save & Continue.
In the Select your target SDK, select Android Native.
Click Save & Continue.
Copy your App ID and click Done.

The OneSignal App ID is the same for both iOS and Android.

You can find it later in your OneSignal app dashboard under Settings > Keys & IDs > OneSignal App ID.

Choose .p8 Auth Key (Recommended) under APNs Authentication Type.
Provide the following:
- .p8 file - the private key file you downloaded in the Set up APNs Authentication Key step above.
- Key ID, Team ID, and App Bundle ID - gathered in the Gather your credentials step above.
Click Save & Continue.
In Select your target SDK, select Native iOS.
Click Save & Continue.
Copy your App ID and click Done.

The OneSignal App ID is the same for both iOS and Android.

You can find it later in your OneSignal app dashboard under Settings > Keys & IDs > OneSignal App ID.

When configuring Apple iOS (APNs), you'll see an Enable iOS 12 direct to history checkbox. This controls whether iOS Provisional Notifications are enabled - notifications that can appear quietly in Notification Center before the user explicitly grants permission. This setting lives entirely in OneSignal's dashboard, not in the Natively Dashboard. See OneSignal's Provisional Push Notifications docs for details.

Natively Dashboard Setup

Before proceeding, make sure you have completed the OneSignal Configuration steps above.

Open your Natively app dashboard and navigate to Features > Notifications > OneSignal.
Toggle the feature to Enabled.
Enter the OneSignal App ID.
Enter the Permission Description.
(Optional) Adjust the Automatically request push permission on app launch checkbox.
Click Save.
Rebuild your app(s).

The Permission Description is the text shown to users when the OS asks them to grant notification access. Explain clearly why your app needs this permission - for example: "We'll send you push notifications when your order ships."

The Automatically request push permission on app launch is enabled by default, triggering the system permission prompt immediately after the user launches the app. Disable it if you'd rather request permission later, at a more relevant moment in your app's flow.

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

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code), JavaScript SDK (Code), or AI Agents (for AI-powered editors like Lovable, Base44, and Replit).

Initialization

Check Plugin

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

Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
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.

Check SDK

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

Open your project's main HTML file (or header settings) and look for the Natively script tag inside the <head> section.
Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., @2.26.0).

<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script>
</head>

To ensure you are using the most up-to-date version, check the Natively GitHub releases page for the latest version number.

Initialize the SDK

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project.

Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project.

Check if the following Natively SDK script is present in the <head> of index.html. If missing or outdated, add it: <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script><script>function nativelyOnLoad() { window.natively.setDebug(true); console.log("✅ Natively SDK loaded successfully."); }</script> For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases

Setup logic

[Element] Natively - Push Notifications (OneSignal)

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.

Events:

OneSignal Player ID Updated - fires whenever the Player ID is successfully retrieved from OneSignal.
Permissions Authorized - fires when the user taps Allow on the native system permission dialog.
Permissions Denied - fires 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 - fires 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. Yes if the user has granted notification permissions.
OneSignal PlayerId - the unique identifier for the current device, used to target this specific user (equivalent to the Subscription ID under Audience > Subscriptions in your OneSignal dashboard).
OneSignal ExternalId - the unique identifier for the current user, used to target this specific user.
Error message - the text of the error encountered during a failed operation (e.g. a failed External ID update).

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, displays a native alert offering to take the user directly to system settings to enable notifications.
Get the user's OneSignal PlayerId - manually refreshes the OneSignal Player ID state.
Get the user's push notification permission status - re-checks the device's notification settings and updates the Permission Status state.
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.

// ============================================================================
// NATIVELY NOTIFICATIONS (ONESIGNAL) - DOCUMENTATION & EXAMPLES
// ============================================================================

const notifications = new NativelyNotifications();

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// notifications.getPermissionStatus(callback)
//   - Checks if the user has currently granted push notification permissions.
//
// notifications.requestPermission(fallbackToSettings, callback)
//   - Prompts the native OS permission dialog.
//   - fallbackToSettings: boolean — if true, prompts the user to open OS settings if previously denied.
//
// notifications.getOneSignalId(callback)
//   - Retrieves the unique OneSignal Player ID for this device.
//   - In the OneSignal dashboard, this is labeled as the Subscription ID.
//
// notifications.getExternalId(callback)
//   - Fetches the custom External ID linked to this Player ID in OneSignal.
//
// notifications.setExternalId({ externalId }, callback)
//   - Links a custom ID (e.g. your database User ID) to this Player ID in OneSignal.
//
// notifications.removeExternalId(callback)
//   - Unlinks the current custom External ID from this Player ID.

// ============================================================================
// CALLBACK RESPONSE FIELDS - getPermissionStatus
// ============================================================================
// resp.status: boolean — true if allowed, false if denied/undetermined

// ============================================================================
// CALLBACK RESPONSE FIELDS - requestPermission
// ============================================================================
// resp.status: boolean — true if the user just tapped Allow, false if Don't Allow

// ============================================================================
// CALLBACK RESPONSE FIELDS - getOneSignalId
// ============================================================================
// resp.playerId: string — the device's OneSignal Player ID (e.g. "a301a5b5-ac6e-...")

// ============================================================================
// CALLBACK RESPONSE FIELDS - getExternalId / setExternalId
// ============================================================================
// resp.externalId: string — the linked External ID, if present
// resp.error: string — present if the operation failed
// resp.message: string — present if the operation failed

// ============================================================================
// CALLBACK RESPONSE FIELDS - removeExternalId
// ============================================================================
// A null/empty response indicates the External ID was successfully removed.
// resp.error: string — present if the operation failed
// resp.message: string — present if the operation failed

// --- Push Notifications. Permissions & Player ID. Start ---

const permission_check_callback = function (resp) {
  console.log(resp.status); // true if allowed, false if denied/undetermined
};

const permission_request_callback = function (resp) {
  console.log(resp.status); // true if the user just tapped Allow, false if Don't Allow
};

const player_id_callback = function (resp) {
  console.log(resp.playerId); // e.g. "a301a5b5-ac6e-..."
};

const fallbackToSettings = false; // true shows a custom alert offering to open OS settings if previously denied

notifications.getPermissionStatus(permission_check_callback);
notifications.requestPermission(fallbackToSettings, permission_request_callback);
notifications.getOneSignalId(player_id_callback);

// --- Push Notifications. Permissions & Player ID. End ---


// --- Push Notifications. External ID Management. Start ---

notifications.getExternalId((resp) => {
  const res = Array.isArray(resp) && resp.length > 0 ? resp[0] : null;

  if (res && res.externalId) {
    console.log("Current External ID:", res.externalId);
  } else {
    console.warn((res && (res.error || res.message)) || "No External ID found.");
  }
});

notifications.setExternalId({ externalId: "user_db_id_12345" }, (resp) => {
  if (resp && resp.externalId) {
    console.log("External ID set successfully to:", resp.externalId);
  } else {
    console.error((resp && (resp.error || resp.message)) || "Failed to set External ID.");
  }
});

notifications.removeExternalId((resp) => {
  if (resp && (resp.error || resp.message)) {
    // Failure — an error or message is present
    console.error("Failed to remove External ID:", resp.error || resp.message);
  } else {
    // Success — a null/empty response indicates the ID was successfully removed
    console.log("External ID removed successfully. Device is now anonymous.");
  }
});

// --- Push Notifications. External ID Management. End ---

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.

Copy the line below and paste it into your AI agent.

[Your feature description] using the Natively Push Notifications (OneSignal) SDK: const notifications = new NativelyNotifications(); notifications.getPermissionStatus(callback) checks current permission status, returning resp.status (boolean). notifications.requestPermission(fallbackToSettings, callback) prompts the native permission dialog — fallbackToSettings: boolean, if true offers to open OS settings when previously denied — returning resp.status (boolean). notifications.getOneSignalId(callback) retrieves the device's OneSignal Player ID, returning resp.playerId (also labeled Subscription ID in the OneSignal dashboard). notifications.getExternalId(callback) and notifications.setExternalId({ externalId }, callback) manage a custom External ID linked to this Player ID, returning resp.externalId on success or resp.error/resp.message on failure. notifications.removeExternalId(callback) unlinks the External ID — a null/empty response indicates success, while resp.error/resp.message indicate failure. For reference: https://docs.buildnatively.com/natively-platform/features/notifications/onesignal-push-notifications

Replace the placeholder at the beginning with a description of what you want to build - for example: "Request push notification permission after the user completes onboarding, and link their account with an External ID on login".

How to use

Client-side calls from the Natively OneSignal Push Notifications SDK can be tested directly in the Natively Preview app, but actually sending notifications should always happen server-side, via your backend - not from the client.

Time the permission request carefully

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

To ensure users receive notifications reliably across all their devices:

Verify Player ID on login. Retrieve the current device's Player ID and compare it against the ID stored in your database for that user.
Register new devices. If the current Player ID isn't in your database, the user is likely on a new device - request push permissions and register it.
Sync via External ID. Once registered, call setExternalId with your internal User ID, so OneSignal knows this device belongs to your user.
Maintain your database. Save the latest Player ID to your user record - consider storing these as a list to support multiple active devices (e.g. iPhone and iPad).

If a user grants permission during their current session, the updated status is reflected in OneSignal starting from the next app launch, not immediately.

Think of the Player ID as the device's digital address - without saving it, your server-side logic won't know where to deliver the notification.

Sending Notifications

Once a user's Player ID or External ID is saved, you can send them a push notification from the OneSignal dashboard, the OneSignal REST API, or - if you're on Bubble - directly from a Backend Workflow.

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.

OneSignal Dashboard - the simplest way to send a test or one-off notification to an individual device, segment, or your entire audience. See OneSignal's Mobile push setup guide.

OneSignal REST API - send notifications programmatically from your backend. See OneSignal's REST API for the full request/response schema or its Server SDKs for other platforms.

Custom Notification Sound

Create a sound file

According to these rules - if the device can't find it, or the format isn't supported, it falls back to the default system sound:

Filename must be natively.wav.
Recommended length under 30 seconds; keep file size small, as large files may not play on some devices.

Natively Dashboard Configuration

Open your Natively app dashboard and navigate to Features > Notifications > OneSignal.
Under Notification custom sound, select Click to upload file and upload your audio file.
Rebuild your app(s).

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

OneSignal Dashboard Configuration

In your OneSignal Dashboard, go to Settings > Push & In-App > Android Notification Channels.
Click Add Group, name it, and click Submit.
Click Add Channel, name it.
Set Importance to Urgent or High (required for the sound to trigger).
Select Custom under the Sound section and set it exactly to natively.
Create the channel.
Click on the created channel and copy the Channel ID.

To trigger a custom sound from your Bubble workflows, navigate to the Custom Sound section of your Send Push action, and enter the copied Channel ID in the Android Channel ID field.

To trigger a custom sound via the OneSignal REST API, include the android_channel_id parameter in your JSON payload, set to the copied Channel ID.

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

To trigger a custom sound from your Bubble workflows, navigate to the Custom Sound section of your Send Push action, and enter natively.wav in the iOS Sound field.

To trigger a custom sound via the OneSignal REST API, include the ios_sound parameter in your JSON payload, set to natively.wav.

Troubleshooting

Notifications don't arrive at all

Go through this checklist:

Confirm OneSignal is enabled and the App ID is entered correctly in the Natively Dashboard under Features > Notifications > OneSignal.
Confirm the app has been rebuilt after enabling or changing this configuration.
Confirm the Player ID or External ID being targeted actually matches the intended user/device - check in Audience > Subscriptions in your OneSignal dashboard.
Check for network issues on the receiving device.
Confirm the app has push permission granted - check app push permissions.
On Android, confirm the relevant notification category isn't disabled.
Confirm the device isn't in Low Power Mode or Do Not Disturb.

Notifications don't arrive on iOS specifically

Your APNs authentication key may need to be regenerated and re-uploaded to OneSignal - see iOS Pre-OneSignal Configuration to generate a new .p8 key if needed.

Notifications don't arrive on Android specifically, but only during development

Delete the app and reinstall it. This is a development-only quirk and won't recur after release to the store.

OneSignal shows an "Invalid Request" error when uploading the Service Account JSON file

OneSignal doesn't indicate the actual cause of this error. The generated Service Account JSON file needs the following roles to be accepted by OneSignal:

Firebase Admin SDK Administrator Service Agent - roles/firebase.sdkAdminServiceAgent .
Firebase App Check Admin - roles/firebaseappcheck.admin .
Service Account Token Creator - roles/iam.serviceAccountTokenCreator .

Check the Google Cloud IAM console and confirm your Firebase Service Account has these roles.

Permission status doesn't match what the user actually granted on iOS

If Enable iOS 12 direct to history (Provisional Notifications) is enabled in your OneSignal dashboard, iOS may silently grant limited, quiet delivery to Notification Center without the user ever seeing a permission prompt. Natively's SDK treats provisional permission as not fully granted - matching how permission behaves on your website - so getPermissionStatus may report notifications as disabled even though the user is receiving them quietly in Notification Center. If you don't need this quiet/provisional behavior and want your app to always request full notification permission (Sounds, Banners, and Notification Center all together), disable Direct to History in the OneSignal dashboard.

Notifications don't work in the Natively Preview app

Devices running the Preview app use a pre-configured sandbox environment and won't appear as active subscriptions in your OneSignal dashboard. To test your actual OneSignal integration, generate a full build of your app instead.

Custom notification sound doesn't play

Confirm the file is named exactly natively.wav, is under 30 seconds, and has a reasonably small file size.

On Android, confirm Importance is set to Urgent or High on the notification channel, and that you've reinstalled the app after configuring the channel.

Not working in a web browser

This is a native feature and will not work in a standard web browser. Test on a real device using a Natively build.

PreviousNotifications NextFirebase - Push Notifications (Advanced)

Last updated 1 month ago

What are OneSignal Push Notifications?

Prerequisites

OneSignal Configuration

Pre-OneSignal Configuration

Create or open your Firebase Project

Confirm Firebase Cloud Messaging API v1 is enabled

Generate a Service Account JSON file

App Capabilities Configuration

Set up APNs Authentication Key

Gather your credentials

OneSignal Dashboard Configuration

Create OneSignal App

Configure your platform

Natively Dashboard Setup

Implementation

Initialization

Setup logic

[Element] Natively - Push Notifications (OneSignal)

Events:

States:

Actions:

How to use

Time the permission request carefully

Sync devices to users on login

Sending Notifications

Custom Notification Sound

Create a sound file

Natively Dashboard Configuration

OneSignal Dashboard Configuration

Troubleshooting