OneSignal: The Complete Implementation Guide (Mobile Push, Web Push, and Email)

A complete guide to implementing OneSignal across Mobile Push, Web Push, and Email: exact steps, common mistakes, and advanced configuration, based on real client implementations at Bildung Data.

OneSignal is the most widely used omnichannel messaging platform in the world — and for good reason. It lets you send push notifications, email, SMS, and In-App Messages from a single place, with a technical integration that's relatively straightforward. But "relatively straightforward" doesn't mean there aren't common mistakes that cost you time, subscribers, and money. This guide, built from our experience implementing OneSignal with real clients, covers every channel with the exact steps to follow — and the mistakes to avoid.

If you need help implementing OneSignal or want a review of your current implementation, reach out to me at guido@bildungdata.com.

📱 Mobile Push & In-App Messages

OneSignal's highest-impact channel. Implemented well, mobile push gets open rates 3-10x higher than email. Here are the critical steps to get it right from the start.

Step 1 — Create the app in OneSignal

Go to onesignal.com → New App/Website → choose "Mobile App". Once created, save the App ID and REST API Key from Settings. You'll need both for the SDK integration and for REST API calls.

Step 2 — Upload your push credentials

Each platform requires its own credentials to send notifications:

Android (FCM): upload the Firebase JSON file from the Firebase console.

iOS (APNs): upload the Apple .p8 certificate from your Apple Developer account.

Huawei: Huawei Push Kit credentials (if your app needs to support devices without Google Play).

Where to configure them: Settings → Push & In-App → Google Android (FCM) / Apple iOS (APNs).

Step 3 — Install the SDK in the app

Add the OneSignal SDK to your project: via Gradle for Android, or CocoaPods / Swift Package Manager for iOS. Once installed, initialize it with your App ID when the app launches — in Application.onCreate() on Android or AppDelegate on iOS.

Step 4 — Configure the small icon on Android

This step is easy to overlook and has a visible impact: without a properly configured icon, Android notifications show a generic white icon. The icon must be a PNG with a transparent background and a monochrome design. Recommended size: 96x96px.

Step 5 — Ask for permission with a soft opt-in In-App Message first

Before showing the OS's native permission prompt, show your own In-App Message explaining the value of notifications. This dramatically improves the opt-in rate.

Critical for iOS: the native iOS prompt can only be shown ONCE. If the user declines, you can't ask again without them manually going into settings. That's why the InApp prompt beforehand is essential — filter for the users who are going to say yes before you spend your one shot.

Step 6 — Configure the Notification Service Extension on iOS

The NSE (Notification Service Extension) is an additional target in Xcode that processes notifications before they're shown. It's required for: Confirmed Delivery, images in notifications, badges, and action buttons.

Without the NSE configured, iOS won't report Confirmed Deliveries and images simply won't appear. You also need to configure App Groups so the NSE and the main app can share data.

Steps 7 and 8 — Testing and metric verification

Send a test message from the Dashboard to a test device. Test with the app in foreground and background, on Android and iOS separately. Then check the Dashboard: active subscribers, opt-in rate by platform, and that messages show the Sent / Delivered / Confirmed statuses.

🌐 Web Push

Web Push lets you send notifications to desktop and mobile browsers without needing an app. Compatible with Chrome, Firefox, Edge, and (since iOS 16.4+) Safari mobile if the user adds the site to their home screen.

Step 1 — Create the app and copy your credentials

onesignal.com → New App/Website → "Web". Save the App ID and REST API Key.

Step 2 — Install the Web SDK

Add the OneSignal JS snippet to the <head> of every page on your site. It can also be installed via Google Tag Manager. Verify it loads without errors in the browser console before moving on.

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
await OneSignal.init({
appId: "TU_APP_ID",
});
});
</script>

Step 3 — Configure the Permission Prompt

You have three options for asking the user for permission:

Slide Prompt: a OneSignal banner that converts better than the direct native prompt.

Native Browser Prompt: the browser's popup directly.

Custom Prompt (InApp beforehand): your own design before the native prompt.

Just like on iOS mobile, the browser's native permission prompt can only be shown ONCE. If the user declines, the browser won't ask again. Use the Slide Prompt or an InApp message beforehand to maximize your chances.

Step 4 — Configure iOS Web Push (Safari mobile)

To support users on iOS 16.4+ in Safari, you need a manifest.json file in your site's root directory. iOS also requires the user to add the site to their home screen before they can subscribe — that's an OS-level limitation, not a OneSignal one.

Steps 5 and 6 — Testing and web metrics

Create a test campaign from the Dashboard and verify receipt in Chrome and Safari. In the Dashboard you should see active subscribers, opt-in rate, and messages with Sent / Delivered status.

⚙️ Advanced Settings — Optional but Highly Recommended

These steps aren't required to send your first message, but they're essential to get OneSignal's real potential: precise segmentation, personalization, and automation.

1 — Identifying users with external_id

When a user logs into your app or site, identify them in OneSignal with your own user ID. This lets you target specific users and cross-reference OneSignal data with your backend or CRM.

// When the user logs in
OneSignal.login('YOUR_USER_ID');

// When they log out
OneSignal.logout();

The external_id should be the same ID you use in your backend. Without it, you can't send transactional notifications to a specific user.

2 — Data Tags for segmentation

Data Tags are user properties you can use to segment and personalize messages. They're sent via SDK or API.

// Set user properties
OneSignal.User.addTags({
plan: 'premium',
city: 'nyc',
last_purchase: '2024-03-15'
});

3 — Custom Events for advanced triggers

Custom Events let you log specific user actions to trigger automations (Journeys) and In-App Messages.

// Track a custom event
OneSignal.trackEvent('purchase', { amount: 100, product: 'course' });

// Other examples
OneSignal.trackEvent('article_read', { category: 'technology' });
OneSignal.trackEvent('checkout_started');

Basic triggers like "app open" or "time on screen" work without any extra code. Custom Events require implementation but unlock advanced personalization possibilities.

4 — Transactional messaging via REST API

For automated sends from your backend (e.g., "order shipped," payment confirmation, system alerts), integrate the POST /notifications endpoint of the OneSignal REST API.

curl --request POST \
--url https://api.onesignal.com/notifications \
--header 'Authorization: Key YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "YOUR_APP_ID",
"include_aliases": { "external_id": ["user_123"] },
"target_channel": "push",
"contents": { "en": "Your order has shipped 🚀" }
}'

5 — Migrating existing subscribers

If you were using another push provider, you can import your historical push tokens and emails via CSV or API so you don't lose your subscriber base.

✉️ Email

OneSignal also handles email, letting you coordinate push and email from a single place. That's very powerful for omnichannel Journeys: if the user doesn't open the push within 24 hours, you automatically send the email.

Step 1 — Enable the Email channel

Go to Settings → Platforms → Email → Activate. By default, OneSignal uses Mailgun with a shared IP. If you already have Sendgrid, your own Mailgun, or Mailchimp, you can connect them so you don't pay OneSignal for email volume. For high volume, you can request a dedicated IP.

Step 2 — Configure your sending domain (SPF / DKIM / DMARC)

This is the most technical step and the most critical for deliverability. Without domain authentication, your emails land in spam. You need to add three DNS records:

SPF: authorizes OneSignal to send emails on behalf of your domain.

DKIM: a cryptographic signature that verifies the email wasn't altered in transit.

DMARC: defines what happens with emails that fail SPF or DKIM.

Your IT team or whoever manages your domain's DNS needs to do this step. Without it, it doesn't matter how good your emails are — they'll go to spam.

Step 3 — From Name, From Email, and Reply-To

Configure the sender name and address users will see (e.g., "MyApp Team" hello@myapp.com). Also set the Reply-To for cases where users reply directly.

Steps 4 and 5 — Importing existing emails and capturing new ones via SDK

If you have a historical email base, import it via CSV or API. Include the external_id to cross-reference with existing user profiles. Only import users who had prior opt-in — never purchased lists.

// Capture the user's email as they enter it
OneSignal.User.addEmail('user@mail.com');

Steps 6 and 7 — Templates and Unsubscribe

Build your templates in OneSignal's drag-and-drop editor. Always include a visible, working unsubscribe link — it's legally required (CAN-SPAM, GDPR). OneSignal handles it automatically if you use its default footer.

Steps 8 and 9 — Testing and deliverability metrics

Before launching, send a test email to your own address and verify: that it arrives, that it doesn't land in spam, that the links work, and that unsubscribe works. Check it in Gmail and Outlook, and in mobile view.

Reference metrics: normal bounce rate is under 2%; target open rate is above 20%. A high bounce rate points to list problems or DNS misconfiguration.

📌 Additional Channels: SMS, WhatsApp, and Integrations

OneSignal also supports SMS via Twilio and WhatsApp via Meta/Twilio Webhooks, making it a truly omnichannel platform. As for native integrations, it connects with Amplitude, Mixpanel, and Appsflyer — very useful for cross-referencing behavioral data with your messaging campaigns.

Conclusion: order matters

OneSignal is a very powerful platform, but like any technical integration, the devil is in the details. The most costly mistakes we see in real implementations are: not configuring the NSE on iOS (you lose Confirmed Delivery and images), burning the native prompt without an InApp message first (you lose opt-in rate for good), and not authenticating your email domain (your emails go to spam from day one).

Following this checklist in order helps you avoid those mistakes and gives you a solid implementation to build campaigns, Journeys, and automations that actually convert on top of. If you need help with your implementation, at Bildung Data we're OneSignal partners and support end-to-end integration projects.

📖 Full official documentation: documentation.onesignal.com