Final Android package
Use the release applicationId from app/build.gradle. If you rename it, also update Firebase, OAuth, App Links, Facebook, and store configuration.
← Main documentation
Connect OneSignal.
EasyPlex 2.4 · notification delivery
Connect OneSignal.
Keep secrets server-side.
EasyPlex already includes OneSignal Android SDK 5.9.6. Buyers connect Firebase Cloud Messaging to OneSignal, save the OneSignal identifiers in the web panel, and let the mobile app initialize from downloaded settings—without hardcoding credentials in Java.
Delivery path
01EasyPlex panelComposes the title, message, image, content target, and segment.
02OneSignal APIAuthenticates the server request with the private app API key.
03Firebase Cloud MessagingUses the Firebase project credentials connected inside OneSignal.
04EasyPlex Android appRegisters the device under the public OneSignal App ID and displays the notification.
Prerequisites
Make the identities agree first
Most notification failures are identity mismatches. Decide the final release package name before creating Firebase and OneSignal applications.
Firebase project
Add an Android app with that exact package name. Download its current google-services.json.
Real test device
Use Android with Google Play services and internet access. Android 13+ requires runtime notification permission.
Step 1 · Google
Prepare Firebase and FCM HTTP v1
Add the Android application
In Firebase Console, create or open the production project. Add Android using the exact release package name, then download
google-services.jsoninto the Android source atapp/google-services.json.Enable Firebase Cloud Messaging API v1
Open the connected Google Cloud project and ensure Firebase Cloud Messaging API v1 is enabled. Do not configure the retired legacy server key workflow for a new installation.
Create the server credential
Generate a dedicated Firebase service-account JSON for messaging. The credential needs permission to create FCM messages and read the Firebase project. Save it in a private password or secrets manager.
Check the Sender ID
In Firebase Project Settings → Cloud Messaging, note the Sender ID. It must match the Firebase project shown when the credential is uploaded to OneSignal.
Step 2 · OneSignal
Create the OneSignal application
Create or select an app
Sign in to OneSignal, create an application for this EasyPlex release, and choose Google Android (FCM) under Settings → Push & In-App.
Upload FCM HTTP v1 credentials
Upload the private Firebase service-account JSON to the Google Android platform configuration. Confirm that the displayed Firebase project and Sender ID match the Android app.
Copy the App ID
Open Settings → Keys & IDs and copy the 36-character OneSignal App ID. This is a public identifier used by the Android SDK.
Create an app-level API key
Create a key scoped to this OneSignal app and store it immediately. This private key allows the EasyPlex server to send notifications. Do not use an Organization API key and do not expose the app key in Android code.
| Value | Where to find it | Where EasyPlex uses it | Secret? |
|---|---|---|---|
| OneSignal App ID | App → Settings → Keys & IDs | Panel setting returned to the Android SDK | No |
| App API key | App → Settings → Keys & IDs → Add Key | EasyPlex backend when sending | Yes |
| Organization ID/key | Organization settings | Not required for normal EasyPlex sending | Organization key is secret |
| FCM service account | Firebase / Google Cloud | Uploaded to OneSignal platform configuration | Yes |
Step 3 · Web panel
Save the provider in EasyPlex
Admin→Settings→Notifications / Firebase→Default Notification Service: OneSignal
- Select OneSignal. The OneSignal Configuration fields appear only when it is the selected notification service.
- OneSignal App ID: paste the public UUID copied from the same OneSignal app connected to your Firebase project.
- OneSignal REST API Key: paste the app-level sending key. This value stays on the Laravel backend and must never be copied into Android resources or Gradle properties.
- OneSignal Segment: enter the exact audience segment name shown in OneSignal. Current accounts commonly use
Subscribed Users; older applications may exposeAll. Custom segments must already exist in OneSignal. - Save the settings. If the panel uses cached settings, run
php artisan optimize:clear, restart the queue worker, and fully restart the Android app.
Step 4 · Android
No OneSignal key belongs in Java
The supplied EasyPlex 2.4 project already contains the required SDK, manifest extension, notification handler, and user login/logout integration.
Included dependency · app/build.gradle
implementation 'com.onesignal:OneSignal:5.9.6'- Place the Firebase client file at
app/google-services.json. - Keep the final package name identical to the Firebase Android app registration.
- Do not add the OneSignal App ID to
Constants.java,strings.xml, or Gradle properties; EasyPlex readsonesignal_app_idfrom protected panel settings. - When the App ID is empty, EasyPlex keeps the OneSignal FCM receiver disabled. After settings download, a non-empty App ID enables the receiver and initializes OneSignal.
- After an EasyPlex user signs in, the app identifies that user to OneSignal with the EasyPlex user ID. Logout clears the OneSignal external identity.
Build a clean release
gradlew.bat clean
gradlew.bat assembleReleaseStep 5 · Verification
Prove registration before sending
Open the app
Install the release-signed build, launch with internet access, and allow notifications when Android prompts.
Find the subscription
In OneSignal → Audience → Subscriptions, confirm the device is subscribed under the expected app and FCM platform.
Send from EasyPlex
Open Admin → Notifications, compose a small custom message, confirm the audience label, and send it.
- Start with a text-only notification to remove image-hosting and deep-link variables.
- Confirm receipt with the app in the foreground, background, and fully closed.
- Then test a movie or series payload and verify that tapping it opens the correct EasyPlex screen.
- Finally test an HTTPS custom link and an image hosted on a publicly reachable HTTPS URL.
Audience
Understand segments and signed-in users
Broadcasts
The panel’s configured segment is used for general notifications. Copy its name exactly from OneSignal, including spaces and capitalization. Use a small test segment before broadcasting to every subscriber.
EasyPlex content notifications can carry a type, TMDB/content identifier, title, message, image, and optional custom URL.
Individual users
EasyPlex associates a signed-in mobile user with OneSignal using the EasyPlex numeric user ID as the external ID. User-targeted backend jobs can therefore address that external identity after the user has opened the configured app and signed in.
If a user reinstalls, changes Firebase project, or has not opened the latest build, allow the app to register again before testing targeted delivery.
Security
Treat the app key like a password
App ID
The App ID identifies the OneSignal application and may be used by the mobile SDK. It cannot authorize message sending by itself.
App API key
Keep it only in the protected backend setting. Never commit, email, screenshot, expose through public settings JSON, or package it in Android.
FCM service account
Store it in OneSignal/Firebase and a secure backup. Never confuse it with Android google-services.json.
- Create separate OneSignal apps and keys for development and production.
- Restrict the OneSignal app key to the VPS public IP when a stable IP and your OneSignal plan support allowlisting.
- Rotate an exposed key immediately, replace it in the panel, clear caches, and send a controlled test.
- Use individual OneSignal team accounts with least privilege and enable multi-factor authentication.
Diagnostics
When a push does not arrive
| Symptom | Likely cause | Corrective action |
|---|---|---|
| Device never appears | Missing/wrong App ID, app has not downloaded settings, no Play services, or notification SDK failed to initialize | Confirm the settings API returns the expected public App ID, reinstall the clean release, open it online, and inspect Logcat for OneSignal. |
| FCM configuration error | Service-account JSON belongs to a different Firebase project or FCM v1 is disabled | Match Firebase Sender ID with OneSignal’s Android platform, enable FCM API v1, and upload the correct credential. |
| 401 / unauthorized | Wrong, expired, rotated, or mismatched OneSignal app API key | Create a key under the same OneSignal app as the App ID, replace the panel value, save, and clear Laravel configuration cache. |
| No subscribed recipients | Permission denied, wrong segment, or device subscription is opted out | Grant Android notification permission, confirm subscription state, and copy an existing segment name exactly. |
| Accepted but not displayed | Battery restrictions, disabled notification channel, device offline, or OEM background limits | Test on another physical device, re-enable the app’s notification channel, remove battery restrictions for testing, and inspect OneSignal delivery status. |
| Correct message, wrong screen | Invalid content type, content ID, or custom link payload | Send a text-only notification first, then test one supported content type and identifier at a time. |
| Only some users receive | Users did not open the current build, changed FCM project, or are outside the selected segment | Ask users to open/update the app, verify their subscription and external ID, then review segment filters. |
Useful Android log filter
adb logcat | findstr /I "OneSignal FirebaseMessaging EasyPlexApp"Final pass
OneSignal launch checklist
One provider. Four matching identities.Panel. OneSignal.
Return to the main handbook ↑