onesignal_flutter

OneSignal Flutter SDK

---

⚠️ Migration Advisory for current OneSignal customers

Our new user-centric APIs and v5.x.x SDKs offer an improved user and data management experience. However, they may not be at 1:1 feature parity with our previous versions yet.

If you are migrating an existing app, we suggest using iOS and Android’s Phased Rollout capabilities to ensure that there are no unexpected issues or edge cases. Here is the documentation for each:

• iOS Phased Rollout
• Google Play Staged Rollouts

If you run into any challenges or have concerns, please contact our support team at support@onesignal.com

---

OneSignal is a free email, sms, push notification, and in-app message service for mobile apps. This SDK makes it easy to integrate your Flutter iOS and/or Android apps with OneSignal.

Installation

See the Setup Guide for setup instructions.

Disabling OneSignal Location

If your app does not use OneSignal.Location, you can exclude the native OneSignal location module from iOS and Android builds.

For Swift Package Manager, CocoaPods, and Android Gradle builds, set ONESIGNAL_DISABLE_LOCATION=true in the environment before resolving or building. The value is case-insensitive, and 1 is also accepted.

In GitHub Actions, you can set it once at the job or step level so Swift Package Manager, CocoaPods, and Gradle builds inherit it:

env:
  ONESIGNAL_DISABLE_LOCATION: true

With the location module disabled, calls to OneSignal.Location are ignored on Android and OneSignal.Location.isShared() returns false.

CocoaPods: app extension targets

CocoaPods only builds OneSignalXCFramework once when every target in your Podfile resolves the same set of subspecs. If the sets differ, it creates one pod variant per set, and each variant tries to write the same extracted framework, which fails the build with:

error: Multiple commands produce '.../XCFrameworkIntermediates/OneSignalXCFramework/OneSignalCore/OneSignalCore.framework'

With location disabled the plugin resolves OneSignalXCFramework/OneSignal and OneSignalXCFramework/OneSignalInAppMessages, so every Notification Service Extension or Widget Extension target must declare those same two subspecs:

target 'OneSignalNotificationServiceExtension' do
  use_frameworks!
  pod 'OneSignalXCFramework/OneSignal', '>= 5.0.0', '< 6.0'
  pod 'OneSignalXCFramework/OneSignalInAppMessages', '>= 5.0.0', '< 6.0'
end

Without the environment variable set, the plugin resolves the umbrella pod, so extension targets should declare pod 'OneSignalXCFramework' instead. Either way the rule is the same: the app target and every extension target must request an identical subspec set.

Applying the change (clearing cached packages)

The environment variable is only read when dependencies are resolved, and each platform caches the resolved set. If you change the variable on an existing project, you must clear the relevant cache and re-resolve in a shell where the variable is exported. Otherwise a stale build can keep (or drop) the location module regardless of the new value.

[!IMPORTANT] When using Xcode or Android Studio, launch the IDE from a terminal that has ONESIGNAL_DISABLE_LOCATION exported. An IDE launched from the Dock/Finder does not inherit variables set only in your shell profile.

Swift Package Manager:

flutter clean
rm -rf ios/.build
rm -rf ~/Library/Caches/org.swift.swiftpm ~/Library/Developer/Xcode/DerivedData/*
ONESIGNAL_DISABLE_LOCATION=true flutter build ios

In Xcode, you can instead use File → Packages → Reset Package Caches (with the variable exported), then build.

CocoaPods:

cd ios
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install

Android Gradle (Gradle re-reads the variable on each configuration, so a clean build is usually enough):

ONESIGNAL_DISABLE_LOCATION=true flutter build apk

On CI, key any DerivedData / SwiftPM / CocoaPods / Gradle caches on the value of ONESIGNAL_DISABLE_LOCATION (or skip restoring them for no-location builds) so a restored cache does not resurrect the location module.

Change Log

See this repository's release tags for a complete change log of every released version.

Support

Please visit this repository's Github issue tracker for feature requests and bug reports related specificly to the SDK. For account issues and support please contact OneSignal support from the OneSignal.com dashboard.

Demo Project

To make things easier, we have published a demo project in the /example folder of this repository.

Supports:

• Tested from iOS 8 to iOS 15
• Tested from Android 4.0.3 (API level 15) to Android 12.0 (31)