You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Symptom-to-fix mapping for the documented behaviours and gotchas. For architecture details see AGENTS.md §4.
Native UI
Symptom
Fix
ShowAlertPopUp does nothing in editor
Editor short-circuit logs to console. Open Window > General > Device Simulator and use the Mobile Services panel to preview platform-shaped mocks inside the simulated phone.
ShowAlertPopUp throws SystemException
Running on an unsupported platform (Standalone, WebGL). Mobile-only API.
iOS alert button callback fires the wrong handler
Two buttons in the same alert share their Text. iOS matches by text — keep button texts unique within a single alert.
RequestReview() does nothing on Android
The generated Gradle project does not contain com.google.android.play:review (or the config opted out). The call logs an error and returns; it does NOT throw.
RequestReview() doesn't show the prompt every time
Working as intended — both iOS SKStoreReviewController and Play In-App Review throttle the prompt frequency.
Notifications
Symptom
Fix
Android notification never displays
At least one GameNotificationChannel must be registered in the MobileNotificationService constructor. First channel passed becomes the default.
ScheduleNotification returns a PendingNotification but the OS never delivers
Editor short-circuit — EditorGameNotification is in-memory only. Build to a device.
Queued notification doesn't fire when app backgrounds
OperatingMode must include Queue for queueing behaviour. Default is NoQueue (schedule with OS immediately).
RescheduleAfterClearing doesn't re-queue
Set pending.Reschedule = true on the returned PendingNotification. Also requires ClearOnForegrounding in the mode.
Notification host survives "reset game" flow
The NotificationService GameObject is DontDestroyOnLoad. Tests / reset flows must destroy it manually.
Gestures
Symptom
Fix
Swiped event never fires
EnhancedTouchSupport not enabled — but GestureController enables/disables it in OnEnable/OnDisable. Check the controller component is active.
Mouse clicks don't trigger swipes/taps in editor
Add a TouchSimulation component to any GameObject in the scene.
Same gesture fires BOTH Tapped and Swiped
_minSwipeDistance <= _maxTapDrift — tune the thresholds.
Haptics
Symptom
Fix
PlayPreset is silent on a paired phone via Unity Remote
Unity Remote relays input/display only — haptics don't transmit. Build a debug player to the device.
By design — -1 is "loop until StopCurrentHaptic". Set Enabled = false or call StopCurrentHaptic.
PlayCustom throws "DontDestroyOnLoad can only be used in play mode" in EditMode tests
PlayCustom always schedules an auto-stop, which spawns the HapticsHost GameObject. Move the test to PlayMode.
Haptic continues after "reset game"
Reset flow destroys the HapticsHost GameObject without stopping the haptic first. Call StopCurrentHaptic() before reset.
Device subsystem
Symptom
Fix
IsLowPowerMode is always false in editor
Editor short-circuits LPM detection. Use EditorPlatformSimulator.SetIosLowPowerMode(true, battery) to drive the change.
device.Att.CurrentStatus returns Authorized on Android
Android has no ATT equivalent — the service returns Authorized unconditionally. Don't read this as "the user authorized"; gate tracking-init on Application.platform == RuntimePlatform.IPhonePlayer.
Cold-start deep link is lost
Construct DeepLinkService early — before scene load. Application.absoluteURL is cleared by Unity once consumed.
Second subscriber to OnLinkActivated doesn't receive the cold-start link
By design — the link represents a single user action, replayed to the FIRST subscriber only.
Permissions
Symptom
Fix
RequestAsync resolves to Granted in editor without prompting
Editor short-circuits to Granted. Use EditorPlatformSimulator.QueuePermissionResult(...) to override.
Check(PhotoLibrary) is Denied or NotDetermined on Android < 13
Below API 33 the service checks READ_EXTERNAL_STORAGE, not READ_MEDIA_IMAGES. Turn on the ReadMediaImages Android manifest toggle; it also declares READ_EXTERNAL_STORAGE up to API 32.
Android location never shows a dialog or stays Limited
Android 12+ needs precise and approximate location declared together (AccessFineLocation adds both). LocationAlways also needs AccessBackgroundLocation and reports Limited until background access is granted.
Check reports Denied and RequestAsync returns instantly
The player refused (or chose "Don't ask again"). Explain the need and call DeviceService.OpenAppSettings().
iOS RequestAsync returns NotDetermined and the log says a permission group is not compiled
The generated Info.plist has no usage description for it, so the group was left out of the binary. Add the description in the Mobile Services Config.
iOS Camera prompt shows blank text
Missing NSCameraUsageDescription. Open Tools > GameLovers > Mobile Services > Select Mobile Services Config or rely on the build postprocessor to fail the build (default).
Game platform
Symptom
Fix
AuthenticateAsync returns false on iOS and the log says Game Center is not enabled
Turn on Game Center in the Mobile Services Config and rebuild. The App ID and provisioning profile need Game Center too.
Play Games calls fail on Android and the log says the SDK is unavailable
Enter the Play Games Project Id in the Mobile Services Config so the build includes play-services-games-v2, then rebuild.
Play Games sign-in fails although the SDK is present
Check in the Play Console that the app's package name and signing certificate are registered with the Play Games project.
IncrementAchievementAsync returns false on iOS
Pass totalSteps; Game Center tracks a percentage and needs the total to convert steps.
Progress calls return false and log that a signed-in player is needed
Call AuthenticateAsync first and check its result.
Shortcuts and in-app browser
Symptom
Fix
Android shortcuts do not appear
They need API 25 or newer and a launcher that supports dynamic shortcuts. Check the log for entries skipped by validation (id, title and absolute URI are required; four at most).
A tapped shortcut does nothing in the game
Construct DeepLinkService early and subscribe to OnLinkActivated; on iOS the tap is collected at construction and on each return to the foreground. Verify the app uses the app-delegate lifecycle, not UIScene.
OpenInAppBrowser opens the external browser on Android
The androidx.browser library is missing. Turn on Include Custom Tabs Dependency in the Mobile Services Config and rebuild.
OpenInAppBrowser logs that it needs an http or https URL
The in-app browser only shows web pages; use Application.OpenURL or a deep-link route for other schemes.
Cloud save
Symptom
Fix
CloudSaveException with NotAuthenticated
Call IGamePlatformServices.AuthenticateAsync first and check its result.
CloudUnavailable on iOS
The player needs an iCloud account for the app. Turn on Cloud Save in the Mobile Services Config so the iCloud Documents capability is added, and enable iCloud for the App ID and provisioning profile.
CloudUnavailable after enabling Game Center
Cloud saves need the Game Center capability compiled in; check the Game platform section.
Android saves fail with Io
Enable Saved Games for the Play Games project in the Play Console.
LoadAsync throws Conflict
ConflictPolicy is Manual and ConflictResolver is null or returned null. Set a resolver or use MostRecent.
Media
Symptom
Fix
SaveToGalleryAsync returns false on iOS with a log about the add-only usage description
Add a PhotoLibraryAddOnly usage description in the Mobile Services Config; the save code is only compiled when NSPhotoLibraryAddUsageDescription is declared.
PickImageAsync returns null on Android and the log says to turn on Include Media Picker
Enable Include Media Picker in the Mobile Services Config and rebuild so the picker activity is declared.
SaveToGalleryAsync fails on Android 9 or older
Enable Write External Storage Legacy and request the storage permission before saving; Android 10 and newer need neither.
Editor / Build
Symptom
Fix
iOS build fails with [GameLovers.MobileServices] iOS build failed because…
A referenced permission has an empty usage description. Open Tools > GameLovers > Mobile Services > Select Mobile Services Config and fill the missing field (the Fill missing English descriptions with suggested copy button is a quick start), or enable Manage Native Build Manually if you manage Info.plist yourself.
Android build doesn't pick up <uses-permission> entries
Inspect the generated application manifest, not mainTemplate.xml. The postprocessor fails when it cannot uniquely identify Unity's application activity; enable Manage Native Build Manually only when another build tool owns the manifest.
The Mobile Samples build menu is missing
Import the single Mobile Services Samples entry from Package Manager and wait for its editor assembly to compile. The package alone intentionally does not install sample menus.
Build All reports a missing or duplicate scene catalog
Reimport Mobile Services Samples and keep exactly one MobileServicesSampleBuildCatalog.asset. The catalog stores serialized SceneAsset references, validates four unique pages in order, and derives current paths at runtime; it does not depend on hand-authored GUID/path strings or the currently open scene.
Build All is disabled
Exit Play Mode and wait for compilation or another player build to finish. The command then installs the canonical four-scene list and opens Unity's native Build Profiles window.
Restore All is disabled
There is no current-session Build All snapshot. Restore state intentionally survives domain reloads but not closing Unity; re-run Build All to capture the current scene list.
The Mobile Services panel is missing from the Device Simulator
Open Window > General > Device Simulator and look in the Control Panel column. The panel is auto-discovered; if it's absent, ensure the GameLovers.MobileServices.Editor assembly compiled (check the Console for errors).
Mocks fired from the panel don't render
The overlay paints into the Game / Simulator view — keep the Device Simulator window open (the overlay is alive only while the Device Simulator panel is open).
Simulator overlay shows generic Unity dialogs
The simulator USS files didn't load. Verify Editor/Explorer/Overlays/MobileSimulator.Common.uss is present in the package and re-import.