{"id":19251031,"url":"https://github.com/onesignal/onesignal-expo-plugin","last_synced_at":"2026-06-11T00:01:26.349Z","repository":{"id":38975696,"uuid":"395418733","full_name":"OneSignal/onesignal-expo-plugin","owner":"OneSignal","description":"The OneSignal Expo plugin allows you to use OneSignal without leaving the managed workflow. Developed in collaboration with SweetGreen.","archived":false,"fork":false,"pushed_at":"2025-05-13T18:43:10.000Z","size":1600,"stargazers_count":170,"open_issues_count":26,"forks_count":61,"subscribers_count":34,"default_branch":"main","last_synced_at":"2025-05-15T10:02:22.141Z","etag":null,"topics":["android","eas","expo","ios","notifications","onesignal","onesignal-notifications","push","push-notifications","react-native"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneSignal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/FileManager.ts","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-12T19:04:44.000Z","updated_at":"2025-05-13T18:43:13.000Z","dependencies_parsed_at":"2023-02-09T16:45:38.562Z","dependency_job_id":"742e719a-cec0-4e08-a055-0fc15d144745","html_url":"https://github.com/OneSignal/onesignal-expo-plugin","commit_stats":{"total_commits":192,"total_committers":14,"mean_commits":"13.714285714285714","dds":0.421875,"last_synced_commit":"368d76a0334d54911f88045b1ba13fd894ca91c3"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-expo-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-expo-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-expo-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneSignal%2Fonesignal-expo-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneSignal","download_url":"https://codeload.github.com/OneSignal/onesignal-expo-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319716,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","eas","expo","ios","notifications","onesignal","onesignal-notifications","push","push-notifications","react-native"],"created_at":"2024-11-09T18:19:41.727Z","updated_at":"2026-06-11T00:01:26.338Z","avatar_url":"https://github.com/OneSignal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eWelcome to the onesignal-expo-plugin 👋\u003c/h1\u003e\n\u003cp\u003e\n  \u003ca href=\"https://www.npmjs.com/package/onesignal-expo-plugin\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Version\" src=\"https://img.shields.io/npm/v/onesignal-expo-plugin.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/OneSignal/onesignal-expo-plugin#readme\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/OneSignal/onesignal-expo-plugin/graphs/commit-activity\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Maintenance\" src=\"https://img.shields.io/badge/Maintained%3F-yes-green.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/onesignal\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Twitter: onesignal\" src=\"https://img.shields.io/twitter/follow/onesignal.svg?style=social\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e The OneSignal Expo plugin allows you to use OneSignal without leaving the managed workflow. Developed in collaboration with SweetGreen.\n\n- 🏠 [Homepage](https://github.com/OneSignal/onesignal-expo-plugin#readme)\n- 🖤 [npm](https://www.npmjs.com/package/onesignal-expo-plugin)\n\n## Overview\n\nThis plugin is an [Expo Config Plugin](https://docs.expo.dev/guides/config-plugins/). It extends the Expo config to allow customizing the prebuild phase of managed workflow builds (no need to eject to a bare workflow). For the purposes of OneSignal integration, the plugin facilitates automatically generating/configuring the necessary native code files needed to get the [OneSignal React-Native SDK](https://github.com/OneSignal/react-native-onesignal) to work. You can think of adding a plugin as adding custom native code.\n\n## Supported environments:\n\n- [The Expo run commands](https://docs.expo.dev/workflow/customizing/) (`expo run:[android|ios]`)\n- [Custom clients](https://blog.expo.dev/introducing-custom-development-clients-5a2c79a9ddf8)\n- [EAS Build](https://docs.expo.dev/build/introduction/)\n\n---\n\n## Install\n\nSee the [Setup Guide](https://documentation.onesignal.com/docs/en/react-native-expo-sdk-setup) for setup instructions.\n\n## Configuration in app.json / app.config.js\n\n### Plugin\n\nAdd the plugin to the **front** of the [plugin array](https://docs.expo.dev/versions/latest/config/app/). It should be added automatically if you ran `npx expo install`. Just make sure it is the first plugin in the array and to configure any desired plugin props:\n\n**app.json**\n\n```json\n{\n  \"plugins\": [\n    [\n      \"onesignal-expo-plugin\",\n      {\n        \"mode\": \"development\"\n      }\n    ]\n  ]\n}\n```\n\nor\n\n**app.config.js/ts**\n\n```js\nimport withOneSignal from 'onesignal-expo-plugin/plugin';\n\nexport default {\n  ...\n  plugins: [\n    withOneSignal({\n      mode: 'development',\n    }),\n  ],\n};\n```\n\n#### Plugin Prop\n\nYou can pass props to the plugin config object to configure:\n\n| Plugin Prop              |                |                                                                                                                                                                                                                                                                                                                                                                               |\n| ------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `mode`                   | **required**   | Used to configure [APNs environment](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment) entitlement. `\"development\"` or `\"production\"`                                                                                                                                                                                                   |\n| `devTeam`                | **deprecated** | Use [`ios.appleTeamId`](https://docs.expo.dev/versions/latest/config/app/#appleteamid) in your Expo config instead. Falls back to this value if `appleTeamId` is not set. e.g: `\"91SW8A37CR\"`                                                                                                                                                                                 |\n| `iPhoneDeploymentTarget` | optional       | Target `IPHONEOS_DEPLOYMENT_TARGET` value to be used when adding the iOS [NSE](https://documentation.onesignal.com/docs/service-extensions). A deployment target is nothing more than the minimum version of the operating system the application can run on. This value should match the value in your Podfile e.g: `\"12.0\"`.                                                |\n| `smallIcons`             | optional       | An array of local paths to small notification icons for Android. Image should be white, transparent, and 96x96 in size. Input images will be automatically scaled down and placed in the appropriate resource folders. e.g: `[\"./assets/ic_stat_onesignal_default.png\"]`. See https://documentation.onesignal.com/docs/customize-notification-icons#small-notification-icons. |\n| `largeIcons`             | optional       | An array of local paths to large notification icons for Android. Image should be white, transparent, and 256x256 in size. e.g: `[\"./assets/ic_onesignal_large_icon_default.png\"]`. See https://documentation.onesignal.com/docs/customize-notification-icons#large-notification-icons.                                                                                        |\n| `smallIconAccentColor`   | optional       | The accent color to use for notification icons on Android. Must be a valid hex value, e.g: `\"#FF0000\"`                                                                                                                                                                                                                                                                        |\n| `iosNSEFilePath`         | optional       | The local path to a custom Notification Service Extension (NSE), written in Swift. The NSE will typically start as a copy of the [default NSE](https://github.com/OneSignal/onesignal-expo-plugin/blob/main/serviceExtensionFiles/NotificationService.swift), then altered to support any custom logic required. e.g: `\"./assets/NotificationService.swift\"`.                 |\n| `appGroupName`           | optional       | Used to configure a custom iOS [App Group](https://documentation.onesignal.com/docs/ios-sdk-setup#step-3-create-an-app-group) name. If not provided, defaults to `\"group.{ios.bundleIdentifier}.onesignal\"`. e.g: `\"group.com.example.myapp.onesignal2\"`.                                                                                                                     |\n| `nseBundleIdentifier`    | optional       | Used to configure a custom bundle identifier suffix for the iOS Notification Service Extension. The full bundle identifier will be `\"{ios.bundleIdentifier}.{nseBundleIdentifier}\"`. If not provided, defaults to `\"OneSignalNotificationServiceExtension\"`.                                                                                                                  |\n| `disableNSE`             | optional       | If `true`, the iOS Notification Service Extension (NSE) will not be added to the project. The NSE is required for badges, confirmed delivery, media attachments, and action buttons. Only disable this if you only need basic push notifications.                                                                                                                             |\n| `disableLocation`        | optional       | If `true`, the native OneSignal location module will be excluded from iOS and Android builds. Use this if your app does not call `OneSignal.Location` and should not link native location APIs.                                                                                                                                                                               |\n| `sounds`                 | optional       | An array of local paths to custom notification sound files (`.wav` only, ≤30 seconds). Files are copied into the app bundle on iOS and `res/raw/` on Android. e.g: `[\"./assets/notification_sound.wav\"]`. See https://documentation.onesignal.com/docs/customize-notification-sounds.                                                                                         |\n| `liveActivities`         | optional       | Opt in to scaffolding an iOS Widget Extension target for OneSignal Live Activities. Use `{}` for the default `OneSignalWidget` target, or pass `targetName`, `bundleIdentifierSuffix`, `widgetFilePath`, or `deploymentTarget` to customize it. See [Live Activities](#live-activities).                                                                                      |\n\n### Disabling Location\n\nWhen `disableLocation` is enabled, the plugin configures native dependency\nresolution so `react-native-onesignal` excludes the location module. On iOS, it\nwrites the Podfile environment setting used during CocoaPods resolution. On\nAndroid, it writes `onesignal.disableLocation=true` to the generated Gradle\nproperties.\n\n### Live Activities\n\nSet `liveActivities` to an object to add the native iOS Widget Extension files and Podfile target required for OneSignal Live Activities.\n\n```json\n{\n  \"plugins\": [\n    [\n      \"onesignal-expo-plugin\",\n      {\n        \"mode\": \"development\",\n        \"liveActivities\": {}\n      }\n    ]\n  ]\n}\n```\n\nThe default widget target is `OneSignalWidget`, with a bundle identifier of `\"{ios.bundleIdentifier}.OneSignalWidget\"`. You can customize it:\n\n```json\n{\n  \"liveActivities\": {\n    \"targetName\": \"MyWidget\",\n    \"bundleIdentifierSuffix\": \"widget\",\n    \"widgetFilePath\": \"./widgets/MyWidgetLiveActivity.swift\",\n    \"deploymentTarget\": \"16.2\"\n  }\n}\n```\n\nThe default generated widget uses OneSignal's `DefaultLiveActivityAttributes`, so call `setupDefault()` from your app code after initializing OneSignal:\n\n```js\nimport { OneSignal } from 'react-native-onesignal';\n\nOneSignal.initialize('YOUR-ONESIGNAL-APP-ID');\nOneSignal.LiveActivities.setupDefault();\n```\n\nRequirements:\n\n- iOS 16.2+ for the generated widget target.\n- A `.p8` APNs key. Apple does not support p12 certificates for Live Activities.\n- `OneSignal.LiveActivities.setupDefault()` must be called before using OneSignal's Live Activity APIs.\n- The widget target depends on `OneSignalXCFramework`, which mirrors the [Cross-platform Live Activity setup](https://documentation.onesignal.com/docs/cross-platform-live-activity-setup#3-add-the-onesignalxcframework-to-your-podfile) and avoids the React Native + `use_frameworks!` host/extension linkage conflict.\n\nSee the [Cross-platform Live Activity SDK setup](https://documentation.onesignal.com/docs/cross-platform-live-activity-setup) and [Live Activities developer setup](https://documentation.onesignal.com/docs/live-activities-developer-setup) for API usage and customization.\n\n### OneSignal App ID\n\nAdd your OneSignal App ID to your [Expo constants via the `extra` param](https://docs.expo.dev/versions/latest/config/app/#extra):\n\n**Example:**\n\n```json\n{\n  \"extra\": {\n    \"oneSignalAppId\": \"\u003cYOUR APP ID HERE\u003e\"\n  }\n}\n```\n\nYou can then access the value to pass to the `initialize` function:\n\n```js\nimport { OneSignal } from 'react-native-onesignal';\nimport Constants from 'expo-constants';\nOneSignal.initialize(Constants.expoConfig.extra.oneSignalAppId);\n```\n\nAlternatively, pass the app ID directly to the function:\n\n```js\nOneSignal.initialize('YOUR-ONESIGNAL-APP-ID');\n```\n\n### Versioning\n\nIn your configuration file, make sure you set:\n\n| Property               | Details                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `version`              | Your app version. Corresponds to `CFBundleShortVersionString` on iOS. It is a human-readable version number of an iOS app, and is typically in the format of \"X.X.X\" (e.g. \"1.0\" or \"2.3.1\"). It is the version number that is typically displayed to users in the App Store and in the app itself. This value will be used in your NSE\\* target's plist file.                                                                       |\n| `ios.buildNumber`      | Build number for your iOS standalone app. Corresponds to `CFBundleVersion` and must match Apple's specified format (e.g: \"42\" or \"100\"). The build number is used by the App Store and iOS to identify and track different versions of an app, and is typically incremented for each new release. It is a number typically used for the developer's and system reference. This value will be used in your NSE\\* target's plist file. |\n| `ios.bundleIdentifier` | Bundle identifier for your iOS standalone app. Corresponds to `CFBundleIdentifier`. It's a unique identifier string that is used to identify an iOS app or bundle. It is typically in the format of `\"com.companyname.appname\"` (e.g. `\"com.example.myapp\"`). This value will be used in your NSE\\* target's plist and entitlements file.                                                                                            |\n\n\\* NSE = Notification Service Extension. Learn more about the NSE [here](https://documentation.onesignal.com/docs/service-extensions).\n\n## EAS (Expo Application Services)\n\nSee our [EAS documentation](EAS.md) for help with EAS.\n\n### iOS Credentials: OneSignal + EAS\n\nTo distribute your iOS application via EAS, you will need to ensure your credentials are set up correctly. See our [credentials setup guide for instructions](IOS_CREDENTIALS_EAS.md).\n\n## Prebuild (optional)\n\nPrebuilding in Expo will result in the generation of the native runtime code for the project (and `ios` and `android` directories being built). By prebuilding, we automatically link and configure the native modules that have implemented CocoaPods, autolinking, and other config plugins. You can think of prebuild like a native code bundler.\n\nWhen you run `expo prebuild` we enter into a custom managed workflow which provides most of the benefits of bare workflows and managed workflows at the same time.\n\n#### Why should I prebuild?\n\nIt may make sense to prebuild locally to inspect config plugin changes and help in debugging issues.\n\n#### Run\n\n```sh\nnpx expo prebuild\n```\n\n```sh\n# nukes changes and rebuilds\nnpx expo prebuild --clean\n```\n\n**EAS Note:** if you choose to stay in a fully managed workflow by not prebuilding, EAS will still run `npx expo prebuild` at build time. You can also prebuild locally but remain in a fully managed workflow by adding the `android` and `ios` directories to your .gitignore.\n\n## Run\n\nThe following commands will prebuild _and_ run your application. Note that for iOS, push notifications will **not** work in the Simulator.\n\n```sh\n# Build and run your native iOS project\nnpx expo run:ios\n\n# Build and run your native Android project\nnpx expo run:android\n```\n\n---\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel free to check [issues page](https://github.com/OneSignal/onesignal-expo-plugin/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n\n## OneSignal\n\n- Website: https://onesignal.com\n- Twitter: [@onesignal](https://twitter.com/onesignal)\n- Github: [@OneSignal](https://github.com/OneSignal)\n- LinkedIn: [@onesignal](https://linkedin.com/company/onesignal)\n\n## 📝 License\n\nCopyright © 2023 [OneSignal](https://github.com/OneSignal).\u003cbr /\u003e\nThis project is [MIT](https://github.com/OneSignal/onesignal-expo-plugin/blob/main/LICENSE) licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonesignal%2Fonesignal-expo-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonesignal%2Fonesignal-expo-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonesignal%2Fonesignal-expo-plugin/lists"}