Skip to content

Re-introduce device push notification support (FCM/APNs) for modern .NET Android/iOS and MAUI #1360

Open

Description

@sacOO7

TL;DR / why this issue exists

Note

Backlog item. Not needed for 2.0 GA. Prioritise it if customers ask for device push-receive on 2.x.

  • What happened: the 1.x Xamarin push packages (ably.io.push.android, ably.io.push.ios) were removed on integration/v2, along with their examples and CI. Xamarin is out of support.
  • The gap: an app on the 2.x packages cannot register a device for push notifications. Sending pushes from a backend (push admin) still works.
  • What is still there: the push engine in Core (activation state machine, LocalDevice, PushChannel, IMobileDevice), with its tests. Only the Android/iOS platform half and a supported way to attach it are missing.
  • Purpose of this issue: record what was removed, what remains, and a proposed plan (modern .NET Android/iOS, MAUI, examples, CI, packaging), so the work can be picked up later without redoing the research.
  • Status: parked, with no committed milestone (see CHANGELOG.md, UPDATING.md and PushNotifications.md on integration/v2). Everything under "Proposed approach" is a proposal, not a decision.

Related issues


1. Background

The 1.x line shipped device push-receive as two Xamarin "satellite" packages on top of ably.io:

NuGet id Project Target Platform dependencies
ably.io.push.android src/IO.Ably.Push.Android monoandroid (Xamarin.Android, TargetFrameworkVersion v11.0; packed into lib/monoandroid with a monoandroid9 dependency group) Xamarin.Firebase.Messaging 122.0.0, Xamarin.Essentials 1.6.1, plus 56 other Xamarin.Android.Support.* / Xamarin.AndroidX.* / Xamarin.Firebase.* transitive bindings
ably.io.push.ios src/IO.Ably.Push.iOS xamarinios10 (Xamarin.iOS) Xamarin.Essentials 1.6.1 (APNs used directly, no Firebase)

Both depended on ably.io [1.2.7,2.0.0]. Microsoft ended support for Xamarin on 1 May 2024. The projects needed a legacy Xamarin VS installer, Android SDK platform 30 and Xcode 14.3 in CI, which tied the packaging workflow to windows-2022 and macos-14.

On integration/v2 these projects were removed as part of the 2.0 restructure. The removal landed in commit a9e07bb2 ("Remove legacy Xamarin heads and push satellites", per PDR-091b plan decisions 5b and 6), via #1333. The commit message says the 1.x packages continue from the 1.x maintenance line, and a modern net8.0-android/net8.0-ios port is a later 2.x follow-up. Commit a2ac31a8 ("Reframe the parked device push port wording") later changed that wording from "post-GA follow-up" to "possible future follow-up, currently parked".

What was removed (commit a9e07bb2)

The last tagged state with all of these is 1.2.19.

Push satellites

  • src/IO.Ably.Push.Android/AndroidMobileDevice.cs implemented IMobileDevice for FCM (token type "fcm"):
    • public static IRealtimeClient Initialise(ClientOptions, PushCallbacks | Action<PushCallbacks>) set IoC.MobileDevice, constructed new AblyRealtime(options, mobileDevice) and called Push.InitialiseStateMachine().
    • public static void OnNewRegistrationToken(string token) forwarded the token to StateMachine.UpdateRegistrationToken(...).
    • RequestRegistrationToken used FirebaseMessaging.Instance.GetToken() with a Java.Lang.Object, IOnCompleteListener.
    • Preferences were stored through Xamarin.Essentials.Preferences. The form factor came from DeviceInfo.Idiom.
  • src/IO.Ably.Push.iOS/AppleMobileDevice.cs implemented IMobileDevice for APNs (token type "apns"):
    • It had the same Initialise and OnNewRegistrationToken(NSData) pattern, which converted the token to hex. It also had OnRegistrationTokenFailed(ErrorInfo).
    • RequestRegistrationToken asked for UNUserNotificationCenter authorization and then called UIApplication.RegisterForRemoteNotifications. It ignored its callback, because the token arrives later through the AppDelegate.
  • src/IO.Ably.Push.Android/IO.Ably.Push.Android.csproj, src/IO.Ably.Push.iOS/IO.Ably.Push.iOS.csproj, their IO.Ably.snk, packages.config, Properties/AssemblyInfo.cs and Android Resources/*.
  • nuget/io.ably.push.android.nuspec, nuget/io.ably.push.ios.nuspec.
  • package-push.sh, package-push.cmd.

Xamarin platform heads (not push-specific, removed in the same commit)

  • src/IO.Ably.Android (monoandroid) and src/IO.Ably.iOS (Xamarin.iOS). These were roughly 30-line Platform.cs heads whose only functional difference was reporting the agent runtime as xamarin. Classic Xamarin consumers now get the netstandard2.0 asset. .NET for Android/iOS and MAUI apps (net8.0-android and later) resolve the nearest compatible asset, which is net7.0. (README.md says "via netstandard2.0" for these, which is only true for classic Xamarin.)

Solutions

  • src/IO.Ably.PackagePush.sln (core plus both push satellites, used for packaging).
  • src/IO.Ably.DotNetPush.sln (core, push satellites, Xamarin heads, DotnetPush, DotnetPush.Android, DotnetPush.iOS and NotificationsPublisher).
  • src/IO.Ably.Xamarin.sln.
  • The removed projects were also dropped from src/IO.Ably.sln and src/IO.Ably.Package.sln.

Examples

  • examples/DotnetPush/ was a Xamarin.Forms app. It had a shared project DotnetPush (Shell UI with State, Channels, Subscribe, Notifications and Log pages), DotnetPush.Android (with MyFirebaseMessaging : FirebaseMessagingService, which handled OnNewToken and OnMessageReceived and posted a local notification) and DotnetPush.iOS (an AppDelegate overriding RegisteredForRemoteNotifications, FailedToRegisterForRemoteNotifications, ReceivedRemoteNotification and DidReceiveRemoteNotification).
  • examples/AndroidSample/ (a Xamarin.Forms Android sample).

Build / CI

  • Cake (cake-build/tasks/build.cake, cake-build/tasks/package.cake, cake-build/helpers/paths.cake):
    • Removed Build.Xamarin (_Restore_Xamarin, _Xamarin_Build).
    • Removed PushPackage (_Restore_Push_Package, _PushPackage_Build_All, _PushPackage_Create_NuGet).
    • Removed the ILRepack _Package_Merge_All task. The ILRepack helper stays for Update.AblyUnity.
    • Removed the XamarinSolution and PushPackageSolution paths.
  • .github/workflows/package.yml:
    • Removed the whole package-push job (macos-14, Xcode 14.3, Android SDK platform 30 / build-tools 30.0.3, .NET 3.1/6/7, legacy Xamarin).
    • Removed the Android SDK and legacy Xamarin installer steps from the main package job.
    • package.yml was later replaced by publish.yml, in 4d820f65.

2. Current state on integration/v2

What still exists (the platform-neutral push engine)

The platform-neutral push engine is still in src/Ably.PubSub.Shared/Push/ and is compiled into Ably.PubSub.Core. Namespace: Ably.PubSub.Push.

File / type Visibility Notes
IMobileDevice public interface SetPreference, GetPreference, ClearPreferences, RequestRegistrationToken(Action<Result<RegistrationToken>>), Callbacks, DevicePlatform, FormFactor. This is the platform seam.
PushCallbacks public class ActivatedCallback, DeactivatedCallback, SyncRegistrationFailedCallback (Func<ErrorInfo, Task>).
ActivationStateMachine (.cs, .States.cs, .Events.cs) internal partial class RSH3 state machine. UpdateRegistrationToken(Result<RegistrationToken>) is the entry point the platform code called.
PushRealtime public sealed class Activate(), Deactivate(), Admin. internal InitialiseStateMachine() and internal StateMachine.
LocalDevice : DeviceDetails public class RSH8. public static Create(clientId, IMobileDevice). Persistence helpers (LoadPersistedLocalDevice, PersistLocalDevice, PersistRegistrationToken, ResetDevice) are internal.
PersistKeys internal static Group names Ably_StateMachine and Ably_Device. Keys ABLY_PUSH_CURRENT_STATE, ABLY_PUSH_PENDING_EVENTS, ABLY_DEVICE_ID, ABLY_DEVICE_SECRET, ABLY_DEVICE_IDENTITY_TOKEN, ABLY_REGISTRATION_TOKEN_TYPE, ABLY_REGISTRATION_TOKEN, and others.
PushChannel public class RSH7: SubscribeDevice, UnsubscribeDevice, SubscribeClient, UnsubscribeClient, ListSubscriptions. It is only created when a mobile device is present (see below).
PushHttp, PushAdmin, IDeviceRegistrations, IPushChannelSubscriptions, DeviceDetails, DeviceFormFactor, RegistrationToken, PushChannelSubscription, List*Request public RSH1 push admin. This is fully available today, through Ably.PubSub.Server and the core.

Platform hooks:

  • src/Ably.PubSub.Shared/IPlatform.cs has IMobileDevice MobileDevice { get; set; }. src/Ably.PubSub.Core/Platform.cs and src/Ably.PubSub.Core.NETFramework/Platform.cs implement it as a plain auto-property, which is never set in product code.
  • src/Ably.PubSub.Shared/IoC.cs (an internal static class) has a MobileDevice { get; set; } property, which delegates to Platform.MobileDevice. IPlatform and Platform are also internal.
  • PubSubRealtimeClient(ClientOptions) passes IoC.MobileDevice into PubSubHttpClient, RealtimeChannels and PushRealtime. There are also internal PubSubRealtimeClient(ClientOptions, IMobileDevice) and internal PubSubHttpClient(ClientOptions, IMobileDevice) overloads. Every client constructor is internal on 2.x; apps create clients only through the doors.
  • RealtimeChannel and HttpChannel only construct a PushChannel when mobileDevice != null. Otherwise their Push getter logs ("…is does not support or is not configured for Push notifications" on realtime, "…not configured for push notifications" on HTTP) and returns null.
  • PubSubRealtimeClient.Device and PubSubHttpClient.Device return LocalDevice.GetInstance(MobileDevice, clientId) when a mobile device is set, and null otherwise.
  • ClientOptions.PushAdminFullWait is still present.

Tests that still exist (src/Ably.PubSub.Tests.Shared/Push/): ActivationStateMachineTests (the largest suite), LocalDeviceTests, PushChannelTests, PushRealtimeTests, PushAdminTests, PushAdminSandboxTests, RegistrationTokenTest, ListDeviceDetailsRequestTests, ListSubscriptionsRequestTests, and the FakeMobileDevice / PushTestHelpers helpers. Together they cover RSH1, RSH3, RSH4–RSH8 against a fake device.

What is missing / what users lose

  • No 2.x code path can enable device push. IMobileDevice is public, but every way to attach one is internal: the IMobileDevice client constructors, IoC.MobileDevice and PushRealtime.InitialiseStateMachine(). PubSubDevice.CreateClient(...) (src/Ably.PubSub.Device/PubSubDevice.cs) calls new PubSubRealtimeClient(options), which picks up IoC.MobileDevice, and that is always null. The Device door also only creates realtime clients; it has no HTTP-client factory (only PubSubServer has CreateHttpClient). So:
    • client.Push.Activate() / Deactivate() always throw AblyException("Realtime push is not enabled...").
    • channel.Push is always null.
    • client.Device is always null.
  • Apps that receive push on the device must stay on ably.io 1.x with ably.io.push.android / ably.io.push.ios. UPDATING.md ("Xamarin and older device apps") and PushNotifications.md say so. 2.0 NuGet release readiness: new Ably.PubSub.* packages, ably.io deprecation, and pre-GA blockers #1356 proposes deprecating both 1.x push packages at 2.0 GA with no alternate.
  • Sending pushes from a backend is not affected: client.Push.Admin works through Ably.PubSub.Server, as does publishing messages with extras.push.

Leftovers that will need attention when this is picked up

  • Stale error text. PushRealtime.Activate() / Deactivate() tell users to call (AblyAndroidMobileDevice / AblyAppleMobileDevice).Initialize(). Neither name existed even in 1.x: the types were AndroidMobileDevice / AppleMobileDevice and the method was Initialise. The RealtimeChannel.Push warning also has a typo ("is does not support").
  • Unreachable enum values. Agent.PlatformRuntime.XamarinAndroid / XamarinIos (src/Ably.PubSub.Shared/Agent.cs) are now unreachable, because Platform.DetectPlatformRuntime() only returns Netstandard20, Net6 or Net7. The agent OS detection already uses OperatingSystem.IsAndroid() / IsIOS() and reports dotnet-android / dotnet-iOS.
  • Out-of-date docs. PushNotifications.md still documents the 1.x Xamarin packages (behind an IMPORTANT banner). It refers to the legacy FCM "server key" setup, and it says remote notifications are not supported on the iOS simulator. Both need rechecking against current FCM (HTTP v1) and Xcode behaviour.
  • Release tooling assumes exactly three packages. cake-build/tasks/release.cake releasePackageSet / releaseDoorNuspecs and cake-build/tasks/package.cake nuspecFiles are the exact lockstep set (Core, Device, Server). The pre-flight fails if nuget/ holds any nuspec outside that set. releaseForbiddenDependencyIds (and the PackagingSpecs tests in src/Ably.PubSub.Tests.DotNET/PubSub/PackagingSpecs.cs) forbid ably.io.push.android / ably.io.push.ios as dependencies. publish.yml pushes only the three ids.
  • No examples solution. examples/NotificationsPublisher is the only remaining example. It references Ably.PubSub.Server, still targets netcoreapp3.1 and is not in any solution (it used to live in IO.Ably.DotNetPush.sln). It publishes messages with extras.push payloads, so it is the natural sender for a push demo.
  • Bugs not to carry forward from 1.x:
    • iOS Initialise passed a possibly-null PushCallbacks straight through, where Android coalesced it to new PushCallbacks().
    • iOS requested UNAuthorizationOptions.Sound twice and never Badge.
    • Both satellites kept a static AblyRealtime _realtimeInstance. That allows only one push-capable client per process. A token arriving before Initialise threw an AblyException on Android; on iOS it hit a NullReferenceException that OnNewRegistrationToken swallowed (the token was silently lost) and OnRegistrationTokenFailed did not catch.
    • The iOS < 10 code paths are dead.
    • AppleMobileDevice.RemovePreference is not part of IMobileDevice.
  • Out-of-support TFMs. The door and core TFMs are netstandard2.0;net6.0;net7.0, and both net6.0 and net7.0 are out of support. A mobile push package would add platform TFMs (see section 4), and that has CI cost. Its dependency on Ably.PubSub.Device would resolve Device's net7.0 asset unless Device gains a newer TFM.
  • Trimming / AOT. README.md ("MAUI configuration") already tells MAUI apps to root Ably.PubSub.Core with TrimmerRootAssembly because the SDK uses reflection. iOS is always AOT-compiled, and the push path serialises LocalDevice, DeviceDetails and queued state-machine events, so the push package and samples must be verified in trimmed Release builds.

3. Goals and non-goals (proposed)

Goals

  • Device push activation, deactivation and registration (RSH2/RSH3) on .NET for Android and .NET for iOS, using FCM and APNs respectively.
  • Reachable only through Ably.PubSub.Device, so push-capable clients are always classified as device-side.
  • Reuse the existing ActivationStateMachine, LocalDevice and PushChannel engine. Platform code should only implement IMobileDevice, plus the token/event plumbing.
  • Work in plain .NET for Android/iOS apps and in .NET MAUI apps, without forcing a MAUI dependency on non-MAUI apps.
  • Modern, maintained example apps, buildable from a solution in this repo.
  • Build, pack and release through the Cake build and the lockstep release tooling.

Non-goals

  • Xamarin (classic) support. It is out of support; 1.x remains the answer there.
  • Rendering or presenting notifications for the app. This is app-owned, as in 1.x. The SDK handles registration, not UI.
  • Push admin changes. That already works in Core/Server.
  • Windows (WNS), macOS desktop or web push. These could be follow-ups, but are not in scope.
  • Unity. Unity ships Ably.PubSub.Device.dll as a plugin (unity/Assets/Ably/Plugins), but Unity mobile builds get push tokens through Unity's own Firebase/notifications packages, so Unity push needs a separate design. It could reuse the public seam in 4.3 (see open questions).
  • Changing the activation state machine semantics, except where needed for spec conformance (tracked separately if found).

4. Proposed approach

4.1 Target frameworks

  • Target the current LTS platform TFMs at implementation time. As of writing that is net10.0-android and net10.0-ios (.NET 10 LTS).
    • net8.0-* was the TFM named in the 2.0 docs. However, .NET 8 reaches end of support in November 2026, and the .NET MAUI / mobile workload support windows are shorter than the runtime's. Check the current .NET, .NET MAUI and .NET for Android/iOS support policies before choosing.
    • Do not pick net6.0-* / net7.0-*. Those mobile workloads are out of support and do not work with current Xcode and Android SDK requirements.
  • Optional: netX.0-maccatalyst, which shares the APNs code path with iOS. Decide based on demand (see open questions).
  • Minimum OS versions (proposal): Android API 21+ (or whatever the chosen Xamarin.Firebase.Messaging binding requires) and iOS 13+ (or whatever the chosen workload requires).

4.2 Packaging options

Option Description Pros Cons
A. Separate push packages (recommended) New Ably.PubSub.Push.Android (netX.0-android) and Ably.PubSub.Push.iOS (netX.0-ios). Each depends on Ably.PubSub.Device at the lockstep version. This matches the names already used in PushNotifications.md. Core/Device/Server stay workload-free, so the Linux/Windows check CI legs and Build.NetStandard are unaffected. Firebase bindings are only pulled in by apps that want push. This mirrors the 1.x split users already know. Two more packages in the lockstep set. Each needs an InternalsVisibleTo grant (or a public seam).
B. Single Ably.PubSub.Push package, multi-targeted One package with netX.0-android;netX.0-ios[;netX.0-maccatalyst]. One package id and one install instruction. Fits MAUI single-project well. Building or packing it needs both workloads, and iOS needs macOS. Android-only apps still see an iOS asset, which is harmless.
C. Multi-target Ably.PubSub.Device itself Add the platform TFMs to the Device door. No new package ids. Push "just works" for device apps. Every consumer of Device on those TFMs gets the Firebase binding dependency. Every CI leg that builds Device needs the mobile workloads, which breaks the current lean Build.NetStandard gate. It couples the Device release to the mobile toolchain.

Recommendation (proposal): Option A, or Option B if a single id is preferred. In both cases the projects should live outside Ably.PubSub.NetStandard.sln, so the existing CI legs and the pre-push lint gate stay workload-free.

4.3 How it plugs into Core / Device

The 1.x satellites called internal Core members directly (IoC.MobileDevice = ..., new AblyRealtime(options, device), Push.InitialiseStateMachine(), Push.StateMachine.UpdateRegistrationToken(...)). On 2.x those are internal and the client constructors are door-only. Options:

  1. Internal access (smallest change). Add InternalsVisibleTo grants (keyless and signed variants) for the new push assemblies to src/Ably.PubSub.Core/Properties/AssemblyInfo.cs, as is already done for Ably.PubSub.Device and Ably.PubSub.Server. Sign the push assemblies with Ably.PubSub.snk under Package builds.

  2. A narrow public seam on the Device door (cleaner long term). For example:

    PubSubDevice.CreateClient(ClientOptions options, IMobileDevice mobileDevice)

    This would call the existing internal PubSubRealtimeClient(ClientOptions, IMobileDevice) and InitialiseStateMachine(). Token updates would go through a small public type, such as PushRealtime.UpdateRegistrationToken(RegistrationToken) or ...Failed(ErrorInfo), rather than reaching into ActivationStateMachine. This would also let third parties (Shiny, Plugin.Firebase users and others) supply their own IMobileDevice.

Either way, the proposed public API under Ably.PubSub should keep the 1.x shape so users can migrate, while removing the global statics:

// Android (in MainApplication / MainActivity / MauiProgram)
var realtime = AndroidPushDevice.CreateClient(options, callbacks => { callbacks.ActivatedCallback = ...; });
// FirebaseMessagingService.OnNewToken(token)  -> AndroidPushDevice.OnNewToken(token);

// iOS (AppDelegate)
var realtime = ApplePushDevice.CreateClient(options, callbacks);
// RegisteredForRemoteNotifications(app, NSData token)        -> ApplePushDevice.OnNewToken(token);
// FailedToRegisterForRemoteNotifications(app, NSError error) -> ApplePushDevice.OnTokenFailed(error);

realtime.Push.Activate();
await realtime.Channels.Get("news").Push.SubscribeDevice();

The type and method names above are placeholders. Finalise them in API review. Also decide whether the realtime client is required, or whether PushHttp should expose Activate too (see open questions).

Other wiring to fix while doing this:

  • Replace IoC.MobileDevice (a process-wide static) and the satellites' static _realtimeInstance with per-client state where possible. If a static registry is unavoidable, because FCM/APNs callbacks arrive on OS-created objects, buffer tokens that arrive before the client exists instead of throwing.
  • LocalDevice.Instance is also static. Confirm that behaviour is correct when more than one client exists.
  • Fix the stale PushRealtime error text, and decide whether to remove or re-point PlatformRuntime.XamarinAndroid / XamarinIos.

4.4 Android (FCM)

  • Firebase bindings: Xamarin.Firebase.Messaging (Microsoft-maintained AndroidX/GPS bindings, still published for .NET for Android TFMs). Pin a version compatible with the chosen TFM. An alternative is to depend on nothing Firebase-specific in the SDK and expose OnNewToken(string) plus a token-request delegate, leaving Firebase to the app or a plugin such as Plugin.Firebase. Trade-off: zero dependency friction against a less turnkey experience.
  • RequestRegistrationToken: FirebaseMessaging.Instance.GetToken() with an IOnCompleteListener (or an await-able wrapper), mapping failures to ErrorInfo. Token type "fcm".
  • App side (documented and shown in the example):
    • A [Service] + [IntentFilter("com.google.firebase.MESSAGING_EVENT")] FirebaseMessagingService subclass that forwards OnNewToken.
    • google-services.json with GoogleServicesJson build action.
    • The POST_NOTIFICATIONS runtime permission on Android 13+.
    • Notification channels.
  • Form factor: use UiModeManager / Configuration.ScreenLayout (or DeviceInfo.Idiom if MAUI Essentials is used) and map it to DeviceFormFactor.

4.5 iOS (APNs)

  • No Firebase. Use APNs directly, as in 1.x. Token type "apns".
  • RequestRegistrationToken: UNUserNotificationCenter.Current.RequestAuthorization(Alert | Badge | Sound), then UIApplication.SharedApplication.RegisterForRemoteNotifications() on the main thread. Only use UIDevice.CheckSystemVersion branches the minimum OS still needs.
  • Token delivery: the app's UIApplicationDelegate.RegisteredForRemoteNotifications(UIApplication, NSData) forwards to the SDK, which hex-encodes NSData.ToArray(). FailedToRegisterForRemoteNotifications forwards the error. Consider an optional helper that a MAUI app can wire through lifecycle events instead of a custom AppDelegate.
  • Entitlements: the aps-environment entitlement and the remote-notification background mode (documented and shown in the example).

4.6 .NET MAUI integration

  • MAUI apps should be able to wire both platforms from MauiProgram using builder.ConfigureLifecycleEvents(...):
    • events.AddiOS(ios => ios.FinishedLaunching(...)), plus whatever registration callbacks the lifecycle API exposes in the target version. Otherwise fall back to a partial AppDelegate.
    • events.AddAndroid(...).
  • Proposal: do not make the push packages depend on Microsoft.Maui.*. Provide either an optional UseAblyPush() extension in a tiny separate package or sample code in the MAUI example.

4.7 Persisting activation / device state

IMobileDevice persists the RSH3 state, the pending-event queue and the LocalDevice (id, deviceSecret, deviceIdentityToken, registration token) through SetPreference, GetPreference and ClearPreferences with the group names in PersistKeys.

  • The 1.x implementation used Xamarin.Essentials.Preferences, which maps to SharedPreferences on Android and NSUserDefaults on iOS.
  • Proposal: implement against the native stores directly (Application.Context.GetSharedPreferences(group, FileCreationMode.Private) on Android, new NSUserDefaults(group, NSUserDefaultsType.SuiteName) or equivalent on iOS). This avoids needing UseMauiEssentials in non-MAUI apps.
  • 1.x upgrade compatibility: if the new implementation reads the same group and key names, using the same native storage that Xamarin.Essentials used, an app upgraded from 1.x keeps its device id and registration instead of registering a new device. Verify the exact storage names Xamarin.Essentials used for a given sharedName and add a test or QA step for it.
  • Consider storing ABLY_DEVICE_SECRET and ABLY_DEVICE_IDENTITY_TOKEN in Keystore/Keychain (the SecureStorage equivalent). Weigh this against the compatibility point above; a one-time migration may be needed.

4.8 Spec conformance (acceptance context)

Reference: https://sdk.ably.com/builds/ably/specification/main/features/ (RSH section).

  • RSH2: platform-specific activate/deactivate. Check whether it should be available on PushHttp as well as PushRealtime.
  • RSH3: the activation state machine (already implemented and tested in ActivationStateMachine*).
  • RSH4/RSH5: event queueing and sequential handling.
  • RSH6: push device authentication (X-Ably-DeviceIdentityToken / X-Ably-DeviceSecret, in Defaults.cs).
  • RSH7: PushChannel subscribe/unsubscribe/list.
  • RSH8: LocalDevice (creation, persistence, client id updates).

The existing unit tests already cite most of these items. The new work mainly adds the platform half and should not regress them.

5. Examples

Where: there is currently no examples solution on integration/v2. IO.Ably.DotNetPush.sln, which used to hold the examples, was deleted. Proposal:

  • Add examples/Ably.PubSub.Examples.sln (or .slnx), kept separate from src/*.sln so the main build and CI do not need mobile workloads. It would contain:
    • examples/Push/AblyPush.Maui/: a MAUI single-project sample for Android and iOS, replacing examples/DotnetPush.
    • Optionally examples/Push/AblyPush.Android/ and examples/Push/AblyPush.iOS/: minimal non-MAUI samples that show the bare platform wiring (FirebaseMessagingService, AppDelegate).
    • examples/NotificationsPublisher/: moved to a supported TFM (it is currently netcoreapp3.1) and kept as the server-side sender, using Ably.PubSub.Server.

What the samples should demonstrate (carried over from the DotnetPush feature set):

  • Client creation through the Device door with push enabled, plus PushCallbacks (activated, deactivated, sync failed).
  • Push.Activate() / Push.Deactivate() with live state display (current RSH3 state, LocalDevice id, registration token).
  • channel.Push.SubscribeDevice() / SubscribeClient() / ListSubscriptions() and the unsubscribe calls.
  • Receiving notifications: foreground and background/data messages, and tapping a notification.
  • Android 13+ POST_NOTIFICATIONS permission and iOS authorization prompts.
  • Server side: PubSubServer with Push.Admin.PublishAsync(...) to a device id or client id, and publishing a channel message with extras.push (NotificationsPublisher).
  • An in-app log view of SDK logs.
  • A README with Firebase/APNs setup. google-services.json and signing assets stay git-ignored.

6. Build, CI and packaging

  • Cake: add targets along the lines of Build.Push / Package.Push, or extend Package behind a flag, building the new projects with dotnet build/dotnet pack. MSBuild + packages.config is no longer needed.
  • Workloads: run dotnet workload install android ios (plus maui for the examples, and maccatalyst if targeted) only in the jobs that build mobile projects. Pin workload versions with a rollback file or global.json workload-set, so builds are reproducible.
  • Runners:
    • Android can build on Linux, Windows or macOS.
    • iOS needs macOS with a matching Xcode, selected for example via maxim-lobanov/setup-xcode. Check whether an iOS class library can be built and packed on Windows without a paired Mac for the chosen workload version.
    • publish.yml currently runs on windows-2022. It will either need a macOS job for the iOS package or a separate build job whose artifacts it reuses.
  • CI checks: add a PR workflow that builds the push packages and the examples in Release with trimming on (no device tests). Keep Build.NetStandard and the check (net6.0..net9.0) legs untouched. The new projects must pass the same StyleCop rulesets (src/Ably.PubSub.ruleset) as the rest of the product code.
  • Release tooling:
    • Extend releasePackageSet / releaseDoorNuspecs-style assertions in cake-build/tasks/release.cake and nuspecFiles in cake-build/tasks/package.cake to include the new package(s). The package(s) should pin Ably.PubSub.Device (or Core) at [$version$].
    • Update PackagingSpecs and the publish.yml push order (Core → Device → Server → Push).
    • Keep ably.io.push.* in releaseForbiddenDependencyIds.
    • Add nuget/ably.pubsub.push.*.nuspec file(s) consistent with the existing nuspecs, because the pre-flight checks the nuget/ folder against releasePackageSet. Moving to SDK-style dotnet pack metadata instead would mean changing that check.
  • Signing:
    • Assemblies: sign with Ably.PubSub.snk under Package builds, matching the InternalsVisibleTo public-key grants.
    • NuGet: follow the same publishing path as the other three packages.
    • Example apps: no store signing in CI. Use debug-signed builds only.
  • NuGet: reserve or claim the new ids (Ably.PubSub.Push.Android, Ably.PubSub.Push.iOS, or Ably.PubSub.Push) together with the other Ably.PubSub.* ids (see 2.0 NuGet release readiness: new Ably.PubSub.* packages, ably.io deprecation, and pre-GA blockers #1356).

7. Testing

  • Unit (existing, keep green): ActivationStateMachineTests, LocalDeviceTests, PushChannelTests, PushRealtimeTests and the rest use FakeMobileDevice. Add tests for any new public seam, for example creating a client with an IMobileDevice through the door, token updates before or after client creation, and multiple clients.
  • Persistence: tests for the Android/iOS preference stores (on-device or instrumented tests where practical), including reading state written by the 1.x Xamarin.Essentials implementation.
  • Platform smoke tests (optional, CI): build-only checks of the examples. Consider an Android emulator job (with Google APIs) that runs activation against the sandbox using a test Firebase project, if the credentials story allows it.
  • Manual QA checklist (per release):
    • Android physical device and emulator with Google APIs: activate, token received, device registered (visible through Push.Admin.DeviceRegistrations), subscribe to channel, receive push in foreground, background and killed states, deactivate.
    • iOS physical device (and simulator, if supported by the current Xcode/macOS): authorization prompt, APNs token, activate, receive alert and background pushes, deactivate.
    • Token refresh (FCM OnNewToken, APNs re-registration) triggers RSH3 GotPushDeviceDetails / update.
    • Client id change updates the registration (ClientIdUpdated path).
    • App upgrade from a 1.x build keeps the same device id (if compatibility is a goal).
    • PushAdminFullWait and push admin from Ably.PubSub.Server against the registered device.

8. Documentation

  • Rewrite PushNotifications.md for 2.x:
    • Remove the "parked" banner.
    • Remove the Xamarin/ably.io.push.* install steps.
    • Update FCM setup to the HTTP v1 / service-account flow in the Ably dashboard.
    • Re-check the iOS simulator limitation.
    • Document plain .NET for Android/iOS and MAUI wiring.
  • README.md: list the push package(s) next to the Device/Server doors.
  • UPDATING.md ("Xamarin and older device apps"): migration from ably.io.push.android / ably.io.push.ios to the new package(s), with an API mapping table (AndroidMobileDevice.Initialise → new API, and so on) and a note on persisted-state compatibility.
  • CHANGELOG.md entry.
  • Ably docs site push pages (.NET tabs), coordinated with the docs team.
  • Revisit the NuGet deprecation message for ably.io.push.* once a replacement exists, so it can name an alternate.

9. Acceptance criteria (if picked up)

  • Push package(s) for netX.0-android and netX.0-ios (current LTS) exist under the Ably.PubSub namespace, built on Ably.PubSub.Device.
  • A device app can create a push-capable client through the Device door only. No direct Core construction is needed.
  • Push.Activate() / Deactivate() complete the RSH3 flow on real Android (FCM) and iOS (APNs) devices. PushCallbacks fire as expected.
  • channel.Push.SubscribeDevice() / SubscribeClient() and the unsubscribe and list calls work for an activated device. client.Device returns the LocalDevice.
  • Device state persists across app restarts (RSH8). The 1.x upgrade behaviour is either supported or explicitly documented as a re-registration.
  • The global static _realtimeInstance pattern is removed or replaced with a safe design. Tokens that arrive before client creation are not lost.
  • Existing push unit tests pass. New tests cover the platform seam.
  • Push package(s) and samples work in trimmed Release builds, including iOS AOT.
  • Core/Device/Server CI legs and ./build.sh --target=Build.NetStandard still need no mobile workloads.
  • Cake target(s) and a CI workflow build and pack the push package(s). The lockstep release pre-flight and post-pack assertions include them.
  • Examples solution with a MAUI push sample (Android and iOS) and an updated NotificationsPublisher that builds in CI.
  • PushNotifications.md, README.md, UPDATING.md and CHANGELOG.md are updated. The stale PushRealtime error text is fixed.

10. Open questions

  1. Packaging: two per-platform packages (Option A), a single multi-targeted Ably.PubSub.Push (Option B), or folding into Ably.PubSub.Device (Option C)?
  2. Core access: more InternalsVisibleTo grants, or a small public seam (PubSubDevice.CreateClient(options, IMobileDevice) plus a public token-update API) that also enables third-party IMobileDevice implementations?
  3. Should the SDK depend on Xamarin.Firebase.Messaging, or stay Firebase-agnostic and take the token from the app or a plugin?
  4. Does activation require a realtime client (the 1.x limitation), or should PushHttp also support Activate per RSH2? If so, the Device door would also need an HTTP-client factory, which it does not have today.
  5. Is Mac Catalyst (APNs) in scope? Windows (WNS)? Unity on Android/iOS?
  6. Must 1.x persisted state be read so upgraded apps keep their device registration? Should the device secret move to secure storage?
  7. Which TFM baseline: the current LTS only, or LTS plus current STS? What policy is there for bumping it?
  8. Is a MAUI helper package (UseAblyPush()) worth shipping, or should the wiring live in docs and samples only?
  9. Is CI device or emulator testing against the sandbox feasible (a Firebase test project, APNs sandbox credentials)?
  10. Release cadence: should the push package(s) be in the lockstep set from day one, or ship as a preview outside it first?

11. References

Repository (removed code, last tagged at 1.2.19)

Repository (current, integration/v2)

  • src/Ably.PubSub.Shared/Push/: IMobileDevice.cs, ActivationStateMachine*.cs, LocalDevice.cs, PushRealtime.cs, PushCallbacks.cs, PersistKeys.cs, PushChannel.cs
  • src/Ably.PubSub.Shared/IoC.cs, src/Ably.PubSub.Shared/IPlatform.cs, src/Ably.PubSub.Core/Platform.cs
  • src/Ably.PubSub.Device/PubSubDevice.cs, src/Ably.PubSub.Core/Properties/AssemblyInfo.cs
  • cake-build/tasks/release.cake, cake-build/tasks/package.cake, .github/workflows/publish.yml
  • PushNotifications.md, UPDATING.md ("Xamarin and older device apps"), CHANGELOG.md (2.0 notes)

Spec

Platform

┆Issue is synchronized with this Jira Story by Unito

Activity

  1. sacOO7 commented on Oct 16, 2026

    @sacOO7
    ContributorAuthor

    Since, we will be dealing with push support for iOS/Android, it would be a good idea to add .NetMaui Examples solution for android/iOS based on existing .netstandard solution alongside push examples for iOS/Android

  2. sacOO7 commented on Oct 21, 2026

    @sacOO7
    ContributorAuthor

    Manual work and device testing needed to bring device push back (Android and iOS)

    ⏱️ At a glance (read this if nothing else)

    People involved

    Who How many What they do Time needed
    Android engineer 1 Firebase setup, emulator and device setup, Android test runs see below
    iOS engineer 1 Apple signing and APNs setup, iPhone and simulator setup, iOS test runs. Needs a Mac and a physical iPhone. see below
    Apple Developer Account Holder 1 (one-off) Grant team access, create the App ID with Push, create the APNs .p8 key about 1 hour, but often days of calendar wait
    Firebase project owner 1 (one-off) Create the SDK QA Firebase project and the FCM v1 service account about 1 hour
    Ably dashboard admin 1 (one-off) Create the test app and upload the FCM and APNs credentials about 1 hour
    Docs reviewer 1 Follow the setup docs from scratch. Must not be the person who wrote them. about half a day, when the docs change

    One .NET developer can do both the Android and iOS roles. If one person does both, the elapsed time equals the Total effort column below.

    Manual testing time using the example app

    Activity Android engineer iOS engineer Total effort Elapsed time with 2 people in parallel
    One-time environment setup 1.5 days 2.5 days 4 days (range 2.5–8) about 2.5 days, plus the Apple access wait
    First full test pass (20 scenarios, using the example app) 1 day 1.5 days 2.5 days (range 1.5–4) about 1.5 days
    First time in total 2.5 days 4 days about 6.5 engineer-days about 1 working week
    Every later release that touches push 1 day 1.5 days 2.5 days (range 1.5–4) about 1.5 days
    Re-check after an Xcode / .NET workload / MAUI / Firebase update (about every 3–6 months) 1 day 1 day 2 days (range 1–3.5) about 1 day

    For example, a year with 4 push-touching releases and 2 toolchain updates costs about 14 engineer-days of manual testing (4 × 2.5 + 2 × 2).

    What these numbers do not include

    • Building the example app and the push packages. That is implementation work: about 10 days for the MAUI example and about 12 days for the Android and iOS packages (likely figures). The whole issue is about 65 engineer-days as a planning figure.
    • Calendar wait for Apple team access and APNs key creation. Start this on day one.
    • Fixing defects the testing finds. One is already known: the RSH6a header bug in the TL;DR.

    This comment covers the manual work this issue needs: the parts that CI cannot do. That means accounts, credentials, devices, local tooling, and hands-on testing by an Android engineer and an iOS engineer. It adds to the plan in the description. It does not replace it.

    Note

    "Android engineer" and "iOS engineer" are roles. One .NET developer can do both, but the iOS role needs a Mac and a physical iPhone. Effort figures are engineer-days given as low / likely / high. They were checked against integration/v2 and current platform docs on 2026-10-21.

    TL;DR

    • Yes, we need both examples and manual testing. The push engine is only unit-tested against a fake IMobileDevice. Real FCM/APNs registration and delivery can only be proven on a device or emulator.
    • One .NET MAUI example app (Android + iOS) is enough. It is both the customer-facing sample and the QA harness. Bare per-platform samples are optional.
    • iOS cannot be tested automatically in hosted CI. Simulator APNs tokens reportedly don't work in Mac VMs. An Android emulator job is possible later but is deferred. So every release that touches push needs a manual test pass on both platforms.
    • Manual effort: see At a glance above. The per-activity breakdown is in section 7.
    • Known blocker the testing will hit: the SDK sends X-Ably-DeviceIdentityToken, but the spec (RSH6a) says the header is X-Ably-DeviceToken (src/Ably.PubSub.Shared/Defaults.cs:78; 1.x has the same constant). Device-authenticated calls such as SubscribeDevice are expected to fail until that is fixed.

    1. Why this can't be fully automated

    What we need to prove Can unit tests prove it? Can CI prove it? So
    The RSH3 activation state machine logic Yes. There are about 150 existing tests using FakeMobileDevice. Yes Already covered
    Getting a real FCM token from Google Play services No Only with an emulator job, a Firebase test project and secrets. Deferred. Manual (Android)
    Getting a real APNs token and the permission prompt No No. Simulator tokens need bare-metal Apple silicon; hosted runners are VMs. Manual (iOS)
    Notification delivery in foreground, background and killed states, and tapping it No No Manual (both)
    Trimmed and AOT Release builds behaving on a device No Build only Manual (both), especially iOS, which always uses AOT
    Setup docs being correct (Firebase, APNs, Ably dashboard) No No Manual walkthrough

    2. Shared prerequisites (needed before either platform can test)

    # Item Details Typical owner
    S1 Ably test app A dedicated sandbox or test app with push enabled. Use an API key that has push-admin and push-subscribe (and publish/subscribe) on the test channels, and supports client-id based auth for the client-id scenarios. Not a production app. Ably staff with dashboard access
    S2 Sender tool examples/NotificationsPublisher, moved off netcoreapp3.1 to a supported TFM and using Ably.PubSub.Server. Alternatively a small script calling Push.Admin.PublishAsync. Used to send to a device id, a client id, and channel messages with extras.push. Implementer
    S3 Secrets handling google-services.json, the APNs .p8 key, the FCM service-account JSON and provisioning profiles are never committed. Add them to .gitignore. Keep the originals in the team password manager or vault. Implementer + whoever owns the accounts
    S4 Test-run record A results table per release (template in section 6), attached to the release PR or issue. Whoever runs the tests
    S5 SDK fix before testing The RSH6a header fix (see TL;DR). Otherwise rows A3/I3 fail for a known reason. Implementer

    3. Android engineer

    3.1 One-time setup: about 1.5 days (1 / 1.5 / 3)

    • Firebase project for SDK QA, for example ably-sdk-push-qa.
      • Register the example app's applicationId.
      • Make sure the Firebase Cloud Messaging API (V1) is enabled.
    • Download google-services.json.
      • Add it to the example under Platforms/Android/ with build action GoogleServicesJson.
      • Keep it git-ignored.
    • FCM service account JSON: create it in Firebase or Google Cloud, then upload it to the Ably test app (S1) under the FCM push configuration. The legacy FCM "server key" no longer works, because the legacy API shut down in 2024.
    • Tooling:
      • the .NET 10 SDK, with the android and maui workloads at the version pinned in the repo
      • JDK 17+
      • Android SDK platform 36 and platform-tools on PATH, with ANDROID_HOME set
    • Emulators, both using Google Play system images (images without Play services never get an FCM token):
      • one on API 33+
      • one on API 26–32, to check behaviour from before the POST_NOTIFICATIONS permission existed
    • Physical devices, with developer options and USB debugging enabled:
      • at least one Android 13+ device with Google Play services
      • ideally one Android 8–12 device

    3.2 Development-time manual work (part of the Android package and example estimates)

    The Android engineer will check these by hand while building the package:

    • The FirebaseMessagingService subclass ([Service(Exported = false)] with the com.google.firebase.MESSAGING_EVENT intent filter) passes OnNewToken to the SDK.
    • A token that arrives before the client exists is buffered, not lost or thrown. On a fresh install, FCM can call OnNewToken before the app creates its Ably client. In 1.x this threw an AblyException.
    • The POST_NOTIFICATIONS runtime permission on Android 13+, and a notification channel (API 26+).
    • MainActivity uses launch mode SingleTop/SingleTask, so taps on a notification arrive through OnNewIntent.
    • minSdk is 23. The current Firebase Messaging binding requires it, even though .NET 10's default is 21.
    • The Release build with trimming on works on a device, not just the Debug build.
    • Android Auto Backup: the SDK stores the device id and secret in shared_prefs/Ably_Device.xml. A backup restored onto a new phone would bring back another device's identity. The example should exclude the Ably_* files in its backup rules (dataExtractionRules/fullBackupContent), and the docs should tell apps to do the same. See row 21.

    3.3 Useful commands

    adb shell pm clear <applicationId>                 # wipe app data (forces new device id / token)
    adb shell am force-stop <applicationId>            # "force stopped" state – FCM will NOT deliver data messages
    adb shell dumpsys deviceidle force-idle            # put device into Doze
    adb shell dumpsys deviceidle unforce               # leave Doze
    adb logcat | grep -i ably                          # SDK logs

    Important

    On Android, swiping the app away and force-stopping it are different. FCM delivers to a swiped-away app but not to a force-stopped one. Test the swipe case as "killed". Document the force-stop behaviour; it is not a bug.


    4. iOS engineer

    4.1 One-time setup: about 2.5 days (1.5 / 2.5 / 5); Apple account lead time not included

    • Apple Developer Program team access (Admin or App Manager role), granted by the org's Account Holder. This is the longest wait; request it first.
    • An App ID for the example's bundle id, with the Push Notifications capability enabled.
    • An APNs auth key (.p8).
      • Record the Key ID and Team ID.
      • The key can be downloaded once only, so store it in the vault straight away.
    • Upload the .p8 to the Ably test app (S1), with topic = bundle id. Use the sandbox APNs environment for development builds.
    • A development provisioning profile that includes the test iPhone's UDID.
    • Tooling:
      • an Apple silicon Mac
      • the exact Xcode version the pinned .NET iOS workload requires (the workload refuses other versions)
      • the .NET 10 SDK with the ios and maui workloads
      • an iOS Simulator runtime (about 8 GB download)
    • Physical iPhone on iOS 16+, with Developer Mode turned on and registered in the team. Ideally also a second device on an older supported iOS version.

    4.2 Development-time manual work (part of the iOS package and example estimates)

    • The app needs a partial AppDelegate : MauiUIApplicationDelegate. MAUI lifecycle events do not expose the APNs callbacks, so these methods must be overridden in it:
      • RegisteredForRemoteNotifications
      • FailedToRegisterForRemoteNotifications
      • DidReceiveRemoteNotification
    • The authorisation request asks for Alert | Badge | Sound. 1.x asked for Sound twice and never Badge.
    • Denying permission must not hang activation. In 1.x a denial caused a null dereference, and activation never completed.
    • A token that arrives before the client exists is buffered. In 1.x it was silently lost.
    • Entitlements and Info.plist:
      • Entitlements.plist has aps-environment = development.
      • Info.plist has UIBackgroundModes = remote-notification.
      • The sample ships its entitlements so that it still builds for people without a signing team (Microsoft's sample uses the same trick).
    • The Release (AOT) build works on a physical iPhone. iOS is always AOT-compiled, and trimming or reflection problems only show up there.

    4.3 Simulator vs device

    • The iOS Simulator can get a real APNs sandbox token and receive real pushes, but only with iOS 16+ and macOS 13+ on Apple silicon or T2 hardware, on bare metal. Use it for fast iteration.
    • The physical iPhone is the pass/fail gate. There are reports of the simulator failing to register on some iOS 26 / macOS combinations and inside VMs.
    • xcrun simctl push <device> <bundle-id> payload.apns, or dragging a .apns file onto the simulator, checks the app's handling of a payload. It does not go through APNs or Ably, so it doesn't count as an end-to-end pass.
    • Production APNs can only be tested with a TestFlight or ad-hoc build and a production-environment key in Ably. That is optional; see I16.

    4.4 Useful tools

    • Console.app, filtered on the device and the app's process, for SDK logs on the device.
    • Settings → Notifications → (app) to reset or deny permission.
    • Settings → General → Background App Refresh affects content-available (silent) pushes. Low Power Mode also throttles them.

    4a. Both engineers

    • Two Ably clients in the same app should share one device registration. They must not overwrite each other's device id or client-id callback. 1.x allowed only one push-capable client per process, so this is new behaviour from the seam redesign. See row 22.

    5. Manual test matrix

    Run every row on Android (physical + Google Play emulator) and iOS (physical; simulator is best effort). Prefixes: A = Android result, I = iOS result.

    Before every row, confirm the device's registration with Push.Admin.DeviceRegistrations.GetAsync(deviceId) / List(...) from the sender tool. For each row, capture:

    • the device id
    • the start of the token
    • the RSH3 state
    • the relevant log lines
    # Scenario Steps Expected result Run
    1 First launch and activate Fresh install → launch → accept the permission prompt → Push.Activate() Prompt shown (POST_NOTIFICATIONS / iOS authorisation). Token obtained. RSH3 reaches WaitingForNewPushDeviceDetails. ActivatedCallback fires. Device listed in push admin with the correct platform (android/ios), formFactor and token type (fcm/apns). Every release
    2 Permission denied Fresh install → deny → activate → later enable in Settings No crash and no hang. The cause is logged. After the permission is granted, notifications display. Every release
    3 Channel subscriptions channel.Push.SubscribeDevice() → ListSubscriptions() → SubscribeClient() → unsubscribe both Each call succeeds and push admin shows the matching subscriptions. This exercises device authentication (RSH6). Every release
    4 Foreground delivery App open → push to the device id from the sender Android OnMessageReceived / iOS WillPresentNotification fires. The example shows the payload. Every release
    5 Background delivery and tap App in background → push → tap the notification The OS shows the notification. Tapping opens the app with the title, body and data intact. Every release
    6 Killed-app delivery and tap Swipe the app away → push → tap The notification shows. Tapping cold-starts the app with the launch payload. (Android force-stop: not delivered, as documented.) Every release
    7 Data-only / silent push Send a data-only message (Android) / content-available: 1 (iOS) Android OnMessageReceived runs in the background. iOS DidReceiveRemoteNotification runs, subject to iOS throttling (note this, not a failure). Every release
    8 Client id and channel extras.push Push to the client id. Publish a channel message with extras.push via NotificationsPublisher. Both arrive on the subscribed device. Every release
    9 Token refresh Android: clear app data or force a token rotation. iOS: reinstall, or another action that changes the token. The new token reaches the SDK and the registration is updated (GotPushDeviceDetails). Push admin shows the new token and pushes still arrive. Every release
    10 Client id change While activated, re-authenticate with a different client id The registration is updated to the new client id. Pushes to the old client id stop arriving. Every release
    11 Deactivate and re-activate Push.Deactivate() → push → Push.Activate() → push DeactivatedCallback fires, the device is removed from push admin, and no push arrives. After re-activating, delivery works again. Every release
    12 Relaunch keeps state While activated, kill and relaunch State is restored from storage. Same device id, no new registration. Every release
    13 Reinstall Uninstall → install → activate A new device id (the old registration is orphaned, which is expected). Activation works. Every release
    14 Release / trimmed / AOT build Repeat rows 1, 3, 4 and 11 with a Release build Same results as Debug. No trimming or AOT failures (watch for serialisation errors in the logs). Every release
    15 Push admin from the server door From Ably.PubSub.Server: Push.Admin.PublishAsync to the device id and client id. DeviceRegistrations.GetAsync/List. Repeat with ClientOptions.PushAdminFullWait = true. Delivered. Admin calls succeed in both modes (fullWait=true makes the server wait for completion before responding). Every release
    16 APNs environment mismatch (iOS only) Production key in Ably with a development build (or the reverse) Delivery fails with BadDeviceToken. This confirms the docs on sandbox vs production. When APNs config or docs change
    17 Offline and power saving Device offline → push → back online. Android Doze / iOS Low Power. Delivered on reconnect, within the TTL. Every release
    18 Upgrade keeps the registration Install the previous released version → activate → upgrade to the candidate Same device id and state. No re-registration. From the second push release onwards
    19 Upgrade from a 1.x Xamarin app (optional) Archived 1.2.19 build, or hand-written preference fixtures → upgrade to 2.x Same device id. Storage names and keys match between Xamarin.Essentials and MAUI, so no migration is expected. Once, if we commit to 1.x continuity
    20 Docs walkthrough Someone who didn't write the setup docs follows PushNotifications.md and the example README from scratch They get to a passing row 1 without help. When the docs change
    21 Backup / restore (Android) Activate → back up via Google backup → restore onto a second device or a wiped emulator The restored install does not reuse the first device's id or secret. It registers as a new device. Once, then when storage changes
    22 Two clients in one app Create two push-capable clients (for example with different client ids) → activate One device id. No crash, and no lost callbacks. Behaviour matches the documented design. When the seam changes

    5a. Out of scope for this testing

    • Rendering notifications for the app (rich media, notification service extensions, custom actions). The app owns this, as in 1.x. The example only shows basic display.
    • Android devices without Google Play services (for example recent Huawei devices). FCM is unavailable there.
    • Mac Catalyst, Windows (WNS), web push and Unity. These are not targets in this issue.
    • Load or volume testing of push delivery. That is an Ably platform concern, not an SDK one.

    6. Results template (per release)

    **SDK version / commit:**
    **Example app build:** Debug / Release
    **Ably app:** sandbox / <name>   **APNs env:** sandbox / production
    
    | # | Android phys (model, OS) | Android emu (API) | iOS phys (model, iOS) | iOS sim (iOS) | Notes / links to logs |
    |---|---|---|---|---|---|
    | 1 | ✅ | ✅ | ✅ | ⚠️ | |
    | … | | | | | |
    
    **Defects found:** (links)
    **Sign-off:** Android – @… / iOS – @…

    7. Effort summary (manual work only)

    Activity Android engineer iOS engineer Total
    One-time setup: accounts, credentials, tooling, devices 1 / 1.5 / 3 1.5 / 2.5 / 5 2.5 / 4 / 8
    First full test pass, rows 1–17 and 20–22, on both device types 0.5 / 1 / 1.5 1 / 1.5 / 2.5 1.5 / 2.5 / 4
    Each later release that touches push, rows 1–15 + 17 (+18) 0.5 / 1 / 1.5 1 / 1.5 / 2.5 1.5 / 2.5 / 4
    Re-check after an Xcode / iOS workload / MAUI / Firebase binding bump (likely every 3–6 months) 0.5 / 1 / 1.5 0.5 / 1 / 2 1 / 2 / 3.5

    Not included:

    • Developer-time device runs while building the packages and the example. They are inside the implementation estimates (Android package about 7 days, iOS package about 5 days, MAUI example about 10 days, all likely figures).
    • Calendar wait for Apple team access and key creation.
    • Fixing any defects the testing finds.

    The whole issue (engine seam, platform packages, CI, release tooling, docs, example and the testing above) is about 65 engineer-days as a planning figure (43–126 range). The full breakdown will follow separately.


    8. Decisions needed from the team

    1. Who owns the Apple Developer team and the Firebase project for SDK QA, and who can upload credentials to the Ably test app?
    2. Device pool: which physical Android and iOS devices (models and OS versions) count as the release gate?
    3. Is a production-APNs check (row 16 via TestFlight) needed per release, or only when the APNs config or docs change?
    4. Do we commit to 1.x → 2.x device-id continuity (row 19)? It is cheap in code, but awkward to test now that 1.x Xamarin apps can't easily be built.
    5. Should the Android emulator job against the sandbox be in scope later? It depends on whether the sandbox accepts FCM v1 credentials, which is not verified yet.
    6. Sign-off rule: must both platform engineers sign off before a push package release, or can one engineer cover both?
  3. sacOO7 commented on Oct 21, 2026

    @sacOO7
    ContributorAuthor

    @maratal had done push api testing for both iOS and android for ably-cli. Once I update the code, I might need to work with @maratal for testing the same behaviour using new dotnet MAUI push code.

  4. sacOO7 commented on Oct 26, 2026

    @sacOO7
    ContributorAuthor

    Since this is parked past 2.0 GA, the push-receive surface will ship in 2.0 as it is now: public, but unable to work. Could a small stop-gap go in before GA, separate from the port?

    • Say it in the API docs. Add XML docs to PushRealtime.Activate/Deactivate, IRealtimeChannel.Push and client.Device saying that device push-receive isn't available in the 2.0 packages, with a link to PushNotifications.md. Push admin (client.Push.Admin) is unaffected.
    • Fix the one message users can actually hit. client.Push.Activate() / Deactivate() throw "Please initialise Ably by calling (AblyAndroidMobileDevice / AblyAppleMobileDevice).Initialize()". Neither type exists, in 2.0 or in 1.x (PushRealtime.cs#L68, #L81). Something like "Device push activation is not supported in Ably.PubSub 2.0; see PushNotifications.md" would do.

    For the leftovers list, two more texts point at APIs that don't exist. They can't be reached today, because channel.Push and client.Device are null without a mobile device, but they will be once the port lands:

    • PushChannel.cs#L41 (also L66, L92, L123, L159) says "call PubSubHttpClient.Push.Activate()", but PushHttp has no Activate.
    • LocalDevice.cs#L140 names AndroidMobileDevice.Initialise() / AppleMobileDevice.Initialise(), which were removed in 2.0.

    The 2.0 docs already say device push-receive is 1.x-only for .NET, so this just makes the SDK say the same thing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or improved functionality.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions