Skip to content

Latest commit

 

History

History
111 lines (88 loc) · 11.1 KB

troubleshooting.md

File metadata and controls

111 lines (88 loc) · 11.1 KB

Troubleshooting

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.
PlayPresetDuration(preset, -1f) keeps vibrating forever 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.