OneSignal SDKs & Libraries: Integration Guides & Code (2026)

SDKs overview

OneSignal provides Software Development Kits (SDKs) and client libraries designed to facilitate the integration of its communication services into various applications. These SDKs abstract much of the complexity involved in managing user subscriptions, sending and receiving notifications, and tracking user engagement. They are available for a range of platforms, including native mobile environments, web browsers, and cross-platform development frameworks, allowing developers to implement push notifications, in-app messaging, email, and SMS functionalities directly within their codebases.

The SDKs are maintained by OneSignal and are regularly updated to support new platform features and address security considerations. Each SDK typically includes methods for initializing the OneSignal service, requesting user permissions for notifications, sending user tags, and handling incoming notifications. The choice of SDK depends on the application's target platform and the development framework being used. For example, a mobile application built with Swift would use the iOS SDK, while a web application would integrate the Web/JS SDK. Cross-platform frameworks like Flutter and React Native have dedicated SDKs that provide a unified API across iOS and Android.

Official SDKs by language

OneSignal maintains a suite of official SDKs for major development platforms and languages. These SDKs are designed to provide comprehensive access to OneSignal's features and are supported directly by the vendor. The table below outlines the primary official SDKs, their corresponding package names or typical installation methods, and their general maturity level as indicated by frequent updates and broad feature support.

Installation

The installation process for OneSignal SDKs varies depending on the platform and development environment. Generally, it involves adding the SDK as a dependency to your project and then initializing it with your OneSignal App ID. Detailed instructions for each platform are available in the OneSignal documentation portal.

iOS (Swift/Objective-C)

For iOS projects, you can integrate the OneSignal SDK using CocoaPods or Swift Package Manager. After adding the dependency, you typically initialize the SDK in your AppDelegate or a similar entry point.

import OneSignalFramework

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)
    OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")
    OneSignal.promptForPushNotifications(userResponse: { accepted in
        print("User accepted notifications: \(accepted)")
    })
    return true
}

Android (Java/Kotlin)

Android integration typically involves adding the OneSignal dependency to your project's build.gradle file and then initializing the SDK within your Application class or main activity.

import com.onesignal.OneSignal

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        OneSignal.setLogLevel(OneSignal.LOG_LEVEL.VERBOSE, OneSignal.LOG_LEVEL.NONE)
        OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")
        OneSignal.initWithContext(this)
        OneSignal.promptForPushNotifications()
    }
}

Web/JavaScript

For web applications, the OneSignal Web SDK can be installed via npm or by including a script tag that loads the SDK from a CDN. Initialization involves calling OneSignal.init() with your App ID and configuring desired settings.

import OneSignal from 'onesignal-web-sdk';

OneSignal.init({
  appId: "YOUR_ONESIGNAL_APP_ID",
  safari_web_id: "YOUR_SAFARI_WEB_ID" // Required for Safari push notifications
});

// Prompt user for push notifications
OneSignal.Slidedown.promptPush();

Flutter

The OneSignal Flutter SDK is added via pubspec.yaml. After installation, the SDK is initialized within the main Dart application entry point.

import 'package:onesignal_flutter/onesignal_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  OneSignal.Debug.setLogLevel(OSLogLevel.verbose);
  OneSignal.Debug.setAlertLevel(OSLogLevel.none);
  OneSignal.initialize("YOUR_ONESIGNAL_APP_ID");
  OneSignal.Notifications.requestPermission(true);
  runApp(MyApp());
}

Quickstart example

A fundamental aspect of integrating OneSignal is initializing the SDK and prompting the user for notification permissions. The following example demonstrates a common quickstart pattern for a web application, including basic event listeners to confirm setup. This boilerplate ensures that the OneSignal service is active and ready to interact with the user's browser for push notifications.

// Load the OneSignal SDK from a CDN in your HTML file's <head> or <body>
// <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>

// In your JavaScript file or within a <script> tag after the SDK loads
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(function(OneSignal) {
  OneSignal.init({
    appId: "YOUR_ONESIGNAL_APP_ID",
    // Recommended for Safari push notifications
    safari_web_id: "YOUR_SAFARI_WEB_PUSH_ID", 
    allowLocalhostAsSecureOrigin: true,
  });

  // Add an event listener for when the SDK is ready
  OneSignal.on("init", function() {
    console.log("OneSignal SDK initialized.");
  });

  // Add an event listener for when the user subscribes to push notifications
  OneSignal.on("subscriptionChange", function(isSubscribed) {
    console.log("The user's subscription state changed to: ", isSubscribed);
    if (isSubscribed) {
      OneSignal.getUserId().then(function(userId) {
        console.log("User ID is: ", userId);
      });
    }
  });

  // Prompt the user for push notification permission (e.g., after a user action)
  // This can be triggered by a button click or automatically after some delay
  document.getElementById('subscribeButton').addEventListener('click', function() {
    OneSignal.Notifications.requestPermission().then(function(permission) {
      if (permission) {
        console.log("Push permission granted!");
      } else {
        console.log("Push permission denied.");
      }
    });
  });
});

This example sets up the OneSignal SDK, logs its initialization, tracks subscription changes, and provides a method to prompt users for notification permissions. It is a foundational setup that can be expanded with additional features like user tagging, in-app messaging, and analytics tracking, as detailed in the OneSignal Web Push Quickstart guide. For development environments, it's often useful to configure logging levels to gain insight into SDK operations, as shown in the Android and iOS examples above.

Community libraries

While OneSignal provides official SDKs for many popular platforms, the developer community also contributes libraries and wrappers for other languages or frameworks. These community-maintained projects can offer solutions for niche use cases or alternative integration patterns. However, their support and feature parity with official SDKs may vary. Developers considering community libraries should review their documentation, recent activity, and ensure they meet the project's requirements for stability and security. Examples of platforms that might see community support include specific server-side languages for interacting with the OneSignal REST API, or less common front-end frameworks. For instance, a developer might find a Node.js library for programmatic API calls, or a Go wrapper for backend integration. These often leverage standard HTTP client libraries, such as those described in MDN Web Docs on the Fetch API, to interact with the OneSignal API endpoints directly.

It is important to note that community libraries are not officially supported by OneSignal, meaning that any issues or bugs encountered would need to be addressed by the community maintainers rather than OneSignal's support channels. Developers are encouraged to check the official OneSignal documentation for the most up-to-date and supported integration methods before opting for a community-developed alternative.

When evaluating a community library, consider the following:

• Active Maintenance: Is the library regularly updated? Are issues being addressed?
• Documentation: Is the documentation clear and comprehensive?
• Feature Parity: Does it support all the OneSignal features you need?
• Community Support: Is there an active community around the library to assist with questions?
• Security Audit: Has the library undergone any security reviews?

For server-side interactions, developers can always use standard HTTP clients in their preferred language to directly interface with the OneSignal REST API, bypassing the need for a specific SDK or library if one is not available or suitable. This approach offers maximum flexibility but requires manual handling of API requests, authentication, and response parsing.