Repository navigation
Description
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 onintegration/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.mdandPushNotifications.mdonintegration/v2). Everything under "Proposed approach" is a proposal, not a decision.
Related issues
- Supersedes (push part): Upgrade deprecated xamarin projects to .NET #1281, "Upgrade deprecated xamarin projects to .NET" (Jira ECO-4725). That issue asked for push support on MAUI. The Xamarin projects it wanted upgraded have now been removed on
integration/v2, so the push-on-modern-.NET work is tracked here. - Context: 2.0 NuGet release readiness: new Ably.PubSub.* packages, ably.io deprecation, and pre-GA blockers #1356, "2.0 NuGet release readiness". It plans to deprecate
ably.io.push.android/ably.io.push.iosat 2.0 GA with no alternate. If this issue ships a replacement package, that deprecation message can be updated to name it.
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.csimplementedIMobileDevicefor FCM (token type"fcm"):public static IRealtimeClient Initialise(ClientOptions, PushCallbacks | Action<PushCallbacks>)setIoC.MobileDevice, constructednew AblyRealtime(options, mobileDevice)and calledPush.InitialiseStateMachine().public static void OnNewRegistrationToken(string token)forwarded the token toStateMachine.UpdateRegistrationToken(...).RequestRegistrationTokenusedFirebaseMessaging.Instance.GetToken()with aJava.Lang.Object, IOnCompleteListener.- Preferences were stored through
Xamarin.Essentials.Preferences. The form factor came fromDeviceInfo.Idiom.
src/IO.Ably.Push.iOS/AppleMobileDevice.csimplementedIMobileDevicefor APNs (token type"apns"):- It had the same
InitialiseandOnNewRegistrationToken(NSData)pattern, which converted the token to hex. It also hadOnRegistrationTokenFailed(ErrorInfo). RequestRegistrationTokenasked forUNUserNotificationCenterauthorization and then calledUIApplication.RegisterForRemoteNotifications. It ignored its callback, because the token arrives later through theAppDelegate.
- It had the same
src/IO.Ably.Push.Android/IO.Ably.Push.Android.csproj,src/IO.Ably.Push.iOS/IO.Ably.Push.iOS.csproj, theirIO.Ably.snk,packages.config,Properties/AssemblyInfo.csand AndroidResources/*.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) andsrc/IO.Ably.iOS(Xamarin.iOS). These were roughly 30-linePlatform.csheads whose only functional difference was reporting the agent runtime asxamarin. Classic Xamarin consumers now get thenetstandard2.0asset. .NET for Android/iOS and MAUI apps (net8.0-androidand later) resolve the nearest compatible asset, which isnet7.0. (README.mdsays "vianetstandard2.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.iOSandNotificationsPublisher).src/IO.Ably.Xamarin.sln.- The removed projects were also dropped from
src/IO.Ably.slnandsrc/IO.Ably.Package.sln.
Examples
examples/DotnetPush/was a Xamarin.Forms app. It had a shared projectDotnetPush(Shell UI with State, Channels, Subscribe, Notifications and Log pages),DotnetPush.Android(withMyFirebaseMessaging : FirebaseMessagingService, which handledOnNewTokenandOnMessageReceivedand posted a local notification) andDotnetPush.iOS(anAppDelegateoverridingRegisteredForRemoteNotifications,FailedToRegisterForRemoteNotifications,ReceivedRemoteNotificationandDidReceiveRemoteNotification).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_Alltask. The ILRepack helper stays forUpdate.AblyUnity. - Removed the
XamarinSolutionandPushPackageSolutionpaths.
- Removed
.github/workflows/package.yml:- Removed the whole
package-pushjob (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.ymlwas later replaced bypublish.yml, in4d820f65.
- Removed the whole
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.cshasIMobileDevice MobileDevice { get; set; }.src/Ably.PubSub.Core/Platform.csandsrc/Ably.PubSub.Core.NETFramework/Platform.csimplement it as a plain auto-property, which is never set in product code.src/Ably.PubSub.Shared/IoC.cs(aninternal static class) has aMobileDevice { get; set; }property, which delegates toPlatform.MobileDevice.IPlatformandPlatformare alsointernal.PubSubRealtimeClient(ClientOptions)passesIoC.MobileDeviceintoPubSubHttpClient,RealtimeChannelsandPushRealtime. There are alsointernal PubSubRealtimeClient(ClientOptions, IMobileDevice)andinternal PubSubHttpClient(ClientOptions, IMobileDevice)overloads. Every client constructor isinternalon 2.x; apps create clients only through the doors.RealtimeChannelandHttpChannelonly construct aPushChannelwhenmobileDevice != null. Otherwise theirPushgetter logs ("…is does not support or is not configured for Push notifications" on realtime, "…not configured for push notifications" on HTTP) and returnsnull.PubSubRealtimeClient.DeviceandPubSubHttpClient.DevicereturnLocalDevice.GetInstance(MobileDevice, clientId)when a mobile device is set, andnullotherwise.ClientOptions.PushAdminFullWaitis 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.
IMobileDeviceis public, but every way to attach one is internal: theIMobileDeviceclient constructors,IoC.MobileDeviceandPushRealtime.InitialiseStateMachine().PubSubDevice.CreateClient(...)(src/Ably.PubSub.Device/PubSubDevice.cs) callsnew PubSubRealtimeClient(options), which picks upIoC.MobileDevice, and that is alwaysnull. The Device door also only creates realtime clients; it has no HTTP-client factory (onlyPubSubServerhasCreateHttpClient). So:client.Push.Activate()/Deactivate()always throwAblyException("Realtime push is not enabled...").channel.Pushis alwaysnull.client.Deviceis alwaysnull.
- Apps that receive push on the device must stay on
ably.io1.x withably.io.push.android/ably.io.push.ios.UPDATING.md("Xamarin and older device apps") andPushNotifications.mdsay 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.Adminworks throughAbly.PubSub.Server, as does publishing messages withextras.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 wereAndroidMobileDevice/AppleMobileDeviceand the method wasInitialise. TheRealtimeChannel.Pushwarning also has a typo ("is does not support"). - Unreachable enum values.
Agent.PlatformRuntime.XamarinAndroid/XamarinIos(src/Ably.PubSub.Shared/Agent.cs) are now unreachable, becausePlatform.DetectPlatformRuntime()only returnsNetstandard20,Net6orNet7. The agent OS detection already usesOperatingSystem.IsAndroid()/IsIOS()and reportsdotnet-android/dotnet-iOS. - Out-of-date docs.
PushNotifications.mdstill 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.cakereleasePackageSet/releaseDoorNuspecsandcake-build/tasks/package.cakenuspecFilesare the exact lockstep set (Core, Device, Server). The pre-flight fails ifnuget/holds any nuspec outside that set.releaseForbiddenDependencyIds(and thePackagingSpecstests insrc/Ably.PubSub.Tests.DotNET/PubSub/PackagingSpecs.cs) forbidably.io.push.android/ably.io.push.iosas dependencies.publish.ymlpushes only the three ids. - No examples solution.
examples/NotificationsPublisheris the only remaining example. It referencesAbly.PubSub.Server, still targetsnetcoreapp3.1and is not in any solution (it used to live inIO.Ably.DotNetPush.sln). It publishes messages withextras.pushpayloads, so it is the natural sender for a push demo. - Bugs not to carry forward from 1.x:
- iOS
Initialisepassed a possibly-nullPushCallbacksstraight through, where Android coalesced it tonew PushCallbacks(). - iOS requested
UNAuthorizationOptions.Soundtwice and neverBadge. - Both satellites kept a
static AblyRealtime _realtimeInstance. That allows only one push-capable client per process. A token arriving beforeInitialisethrew anAblyExceptionon Android; on iOS it hit aNullReferenceExceptionthatOnNewRegistrationTokenswallowed (the token was silently lost) andOnRegistrationTokenFaileddid not catch. - The iOS < 10 code paths are dead.
AppleMobileDevice.RemovePreferenceis not part ofIMobileDevice.
- iOS
- Out-of-support TFMs. The door and core TFMs are
netstandard2.0;net6.0;net7.0, and bothnet6.0andnet7.0are out of support. A mobile push package would add platform TFMs (see section 4), and that has CI cost. Its dependency onAbly.PubSub.Devicewould resolve Device'snet7.0asset unless Device gains a newer TFM. - Trimming / AOT.
README.md("MAUI configuration") already tells MAUI apps to rootAbly.PubSub.CorewithTrimmerRootAssemblybecause the SDK uses reflection. iOS is always AOT-compiled, and the push path serialisesLocalDevice,DeviceDetailsand 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,LocalDeviceandPushChannelengine. Platform code should only implementIMobileDevice, 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.dllas 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-androidandnet10.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.Messagingbinding 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:
-
Internal access (smallest change). Add
InternalsVisibleTogrants (keyless and signed variants) for the new push assemblies tosrc/Ably.PubSub.Core/Properties/AssemblyInfo.cs, as is already done forAbly.PubSub.DeviceandAbly.PubSub.Server. Sign the push assemblies withAbly.PubSub.snkunderPackagebuilds. -
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)andInitialiseStateMachine(). Token updates would go through a small public type, such asPushRealtime.UpdateRegistrationToken(RegistrationToken)or...Failed(ErrorInfo), rather than reaching intoActivationStateMachine. This would also let third parties (Shiny, Plugin.Firebase users and others) supply their ownIMobileDevice.
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_realtimeInstancewith 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.Instanceis also static. Confirm that behaviour is correct when more than one client exists.- Fix the stale
PushRealtimeerror text, and decide whether to remove or re-pointPlatformRuntime.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 exposeOnNewToken(string)plus a token-request delegate, leaving Firebase to the app or a plugin such asPlugin.Firebase. Trade-off: zero dependency friction against a less turnkey experience. RequestRegistrationToken:FirebaseMessaging.Instance.GetToken()with anIOnCompleteListener(or anawait-able wrapper), mapping failures toErrorInfo. Token type"fcm".- App side (documented and shown in the example):
- A
[Service]+[IntentFilter("com.google.firebase.MESSAGING_EVENT")]FirebaseMessagingServicesubclass that forwardsOnNewToken. google-services.jsonwithGoogleServicesJsonbuild action.- The
POST_NOTIFICATIONSruntime permission on Android 13+. - Notification channels.
- A
- Form factor: use
UiModeManager/Configuration.ScreenLayout(orDeviceInfo.Idiomif MAUI Essentials is used) and map it toDeviceFormFactor.
4.5 iOS (APNs)
- No Firebase. Use APNs directly, as in 1.x. Token type
"apns". RequestRegistrationToken:UNUserNotificationCenter.Current.RequestAuthorization(Alert | Badge | Sound), thenUIApplication.SharedApplication.RegisterForRemoteNotifications()on the main thread. Only useUIDevice.CheckSystemVersionbranches the minimum OS still needs.- Token delivery: the app's
UIApplicationDelegate.RegisteredForRemoteNotifications(UIApplication, NSData)forwards to the SDK, which hex-encodesNSData.ToArray().FailedToRegisterForRemoteNotificationsforwards the error. Consider an optional helper that a MAUI app can wire through lifecycle events instead of a customAppDelegate. - Entitlements: the
aps-environmententitlement and theremote-notificationbackground mode (documented and shown in the example).
4.6 .NET MAUI integration
- MAUI apps should be able to wire both platforms from
MauiProgramusingbuilder.ConfigureLifecycleEvents(...):events.AddiOS(ios => ios.FinishedLaunching(...)), plus whatever registration callbacks the lifecycle API exposes in the target version. Otherwise fall back to a partialAppDelegate.events.AddAndroid(...).
- Proposal: do not make the push packages depend on
Microsoft.Maui.*. Provide either an optionalUseAblyPush()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 toSharedPreferenceson Android andNSUserDefaultson 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 needingUseMauiEssentialsin 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
sharedNameand add a test or QA step for it. - Consider storing
ABLY_DEVICE_SECRETandABLY_DEVICE_IDENTITY_TOKENin Keystore/Keychain (theSecureStorageequivalent). 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
PushHttpas well asPushRealtime. - 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, inDefaults.cs). - RSH7:
PushChannelsubscribe/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 fromsrc/*.slnso 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, replacingexamples/DotnetPush.- Optionally
examples/Push/AblyPush.Android/andexamples/Push/AblyPush.iOS/: minimal non-MAUI samples that show the bare platform wiring (FirebaseMessagingService,AppDelegate). examples/NotificationsPublisher/: moved to a supported TFM (it is currentlynetcoreapp3.1) and kept as the server-side sender, usingAbly.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,LocalDeviceid, 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_NOTIFICATIONSpermission and iOS authorization prompts. - Server side:
PubSubServerwithPush.Admin.PublishAsync(...)to a device id or client id, and publishing a channel message withextras.push(NotificationsPublisher). - An in-app log view of SDK logs.
- A README with Firebase/APNs setup.
google-services.jsonand signing assets stay git-ignored.
6. Build, CI and packaging
- Cake: add targets along the lines of
Build.Push/Package.Push, or extendPackagebehind a flag, building the new projects withdotnet build/dotnet pack. MSBuild +packages.configis no longer needed. - Workloads: run
dotnet workload install android ios(plusmauifor the examples, andmaccatalystif targeted) only in the jobs that build mobile projects. Pin workload versions with a rollback file orglobal.jsonworkload-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.ymlcurrently runs onwindows-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.NetStandardand thecheck (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 incake-build/tasks/release.cakeandnuspecFilesincake-build/tasks/package.caketo include the new package(s). The package(s) should pinAbly.PubSub.Device(or Core) at[$version$]. - Update
PackagingSpecsand thepublish.ymlpush order (Core → Device → Server → Push). - Keep
ably.io.push.*inreleaseForbiddenDependencyIds. - Add
nuget/ably.pubsub.push.*.nuspecfile(s) consistent with the existing nuspecs, because the pre-flight checks thenuget/folder againstreleasePackageSet. Moving to SDK-styledotnet packmetadata instead would mean changing that check.
- Extend
- Signing:
- Assemblies: sign with
Ably.PubSub.snkunderPackagebuilds, matching theInternalsVisibleTopublic-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.
- Assemblies: sign with
- NuGet: reserve or claim the new ids (
Ably.PubSub.Push.Android,Ably.PubSub.Push.iOS, orAbly.PubSub.Push) together with the otherAbly.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,PushRealtimeTestsand the rest useFakeMobileDevice. Add tests for any new public seam, for example creating a client with anIMobileDevicethrough 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 RSH3GotPushDeviceDetails/ update. - Client id change updates the registration (
ClientIdUpdatedpath). - App upgrade from a 1.x build keeps the same device id (if compatibility is a goal).
-
PushAdminFullWaitand push admin fromAbly.PubSub.Serveragainst the registered device.
- Android physical device and emulator with Google APIs: activate, token received, device registered (visible through
8. Documentation
- Rewrite
PushNotifications.mdfor 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 fromably.io.push.android/ably.io.push.iosto the new package(s), with an API mapping table (AndroidMobileDevice.Initialise→ new API, and so on) and a note on persisted-state compatibility. -
CHANGELOG.mdentry. - 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-androidandnetX.0-ios(current LTS) exist under theAbly.PubSubnamespace, built onAbly.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.PushCallbacksfire as expected. -
channel.Push.SubscribeDevice()/SubscribeClient()and the unsubscribe and list calls work for an activated device.client.Devicereturns theLocalDevice. - 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
_realtimeInstancepattern 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.NetStandardstill 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
NotificationsPublisherthat builds in CI. -
PushNotifications.md,README.md,UPDATING.mdandCHANGELOG.mdare updated. The stalePushRealtimeerror text is fixed.
10. Open questions
- Packaging: two per-platform packages (Option A), a single multi-targeted
Ably.PubSub.Push(Option B), or folding intoAbly.PubSub.Device(Option C)? - Core access: more
InternalsVisibleTogrants, or a small public seam (PubSubDevice.CreateClient(options, IMobileDevice)plus a public token-update API) that also enables third-partyIMobileDeviceimplementations? - Should the SDK depend on
Xamarin.Firebase.Messaging, or stay Firebase-agnostic and take the token from the app or a plugin? - Does activation require a realtime client (the 1.x limitation), or should
PushHttpalso supportActivateper RSH2? If so, the Device door would also need an HTTP-client factory, which it does not have today. - Is Mac Catalyst (APNs) in scope? Windows (WNS)? Unity on Android/iOS?
- Must 1.x persisted state be read so upgraded apps keep their device registration? Should the device secret move to secure storage?
- Which TFM baseline: the current LTS only, or LTS plus current STS? What policy is there for bumping it?
- Is a MAUI helper package (
UseAblyPush()) worth shipping, or should the wiring live in docs and samples only? - Is CI device or emulator testing against the sandbox feasible (a Firebase test project, APNs sandbox credentials)?
- 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)
- Android satellite: https://github.com/ably/ably-pubsub-dotnet/tree/1.2.19/src/IO.Ably.Push.Android (
AndroidMobileDevice.cs) - iOS satellite: https://github.com/ably/ably-pubsub-dotnet/tree/1.2.19/src/IO.Ably.Push.iOS (
AppleMobileDevice.cs) - Push example app: https://github.com/ably/ably-pubsub-dotnet/tree/1.2.19/examples/DotnetPush
- Nuspecs: https://github.com/ably/ably-pubsub-dotnet/tree/1.2.19/nuget
- Removal commit:
a9e07bb2988db187fedb6b19f381d2d7ab635518("Remove legacy Xamarin heads and push satellites"), via [Split 1/3] Restructure into Ably.PubSub.Core (assembly rename, drop Xamarin heads and push satellites, version 2.0.0) #1333 - Wording commit:
a2ac31a88e267e55608a340bf8af33248782fd7c("Reframe the parked device push port wording") - Related issues: Upgrade deprecated xamarin projects to .NET #1281 (Xamarin → .NET / MAUI push), 2.0 NuGet release readiness: new Ably.PubSub.* packages, ably.io deprecation, and pre-GA blockers #1356 (2.0 NuGet release readiness,
ably.io.push.*deprecation)
Repository (current, integration/v2)
src/Ably.PubSub.Shared/Push/:IMobileDevice.cs,ActivationStateMachine*.cs,LocalDevice.cs,PushRealtime.cs,PushCallbacks.cs,PersistKeys.cs,PushChannel.cssrc/Ably.PubSub.Shared/IoC.cs,src/Ably.PubSub.Shared/IPlatform.cs,src/Ably.PubSub.Core/Platform.cssrc/Ably.PubSub.Device/PubSubDevice.cs,src/Ably.PubSub.Core/Properties/AssemblyInfo.cscake-build/tasks/release.cake,cake-build/tasks/package.cake,.github/workflows/publish.ymlPushNotifications.md,UPDATING.md("Xamarin and older device apps"),CHANGELOG.md(2.0 notes)
Spec
- Ably features spec, push (RSH1–RSH8): https://sdk.ably.com/builds/ably/specification/main/features/
Platform
- Xamarin support policy (ended 1 May 2024): https://dotnet.microsoft.com/platform/support/policy/xamarin
- .NET support policy: https://dotnet.microsoft.com/platform/support/policy/dotnet-core
- .NET MAUI support policy: https://dotnet.microsoft.com/platform/support/policy/maui
- Migrating from Xamarin to .NET / MAUI: https://learn.microsoft.com/dotnet/maui/migration/
- MAUI platform lifecycle events: https://learn.microsoft.com/dotnet/maui/fundamentals/app-lifecycle
- FCM HTTP v1 migration: https://firebase.google.com/docs/cloud-messaging/migrate-v1
- APNs registration: https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns
- Ably push docs: https://ably.com/docs/push
┆Issue is synchronized with this Jira Story by Unito
Activity
sacOO7 commentedon Oct 16, 2026
Since, we will be dealing with push support for iOS/Android, it would be a good idea to add
.NetMauiExamples solution for android/iOS based on existing.netstandardsolution alongside push examples foriOS/AndroidsacOO7 commentedon Oct 21, 2026
Manual work and device testing needed to bring device push back (Android and iOS)
⏱️ At a glance (read this if nothing else)
People involved
.p8keyOne .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
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
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/v2and current platform docs on 2026-10-21.TL;DR
IMobileDevice. Real FCM/APNs registration and delivery can only be proven on a device or emulator.X-Ably-DeviceIdentityToken, but the spec (RSH6a) says the header isX-Ably-DeviceToken(src/Ably.PubSub.Shared/Defaults.cs:78; 1.x has the same constant). Device-authenticated calls such asSubscribeDeviceare expected to fail until that is fixed.1. Why this can't be fully automated
FakeMobileDevice.2. Shared prerequisites (needed before either platform can test)
push-adminandpush-subscribe(andpublish/subscribe) on the test channels, and supports client-id based auth for the client-id scenarios. Not a production app.examples/NotificationsPublisher, moved offnetcoreapp3.1to a supported TFM and usingAbly.PubSub.Server. Alternatively a small script callingPush.Admin.PublishAsync. Used to send to a device id, a client id, and channel messages withextras.push.google-services.json, the APNs.p8key, 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.3. Android engineer
3.1 One-time setup: about 1.5 days (1 / 1.5 / 3)
ably-sdk-push-qa.applicationId.google-services.json.Platforms/Android/with build actionGoogleServicesJson.androidandmauiworkloads at the version pinned in the repoPATH, withANDROID_HOMEsetPOST_NOTIFICATIONSpermission existed3.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:
FirebaseMessagingServicesubclass ([Service(Exported = false)]with thecom.google.firebase.MESSAGING_EVENTintent filter) passesOnNewTokento the SDK.OnNewTokenbefore the app creates its Ably client. In 1.x this threw anAblyException.POST_NOTIFICATIONSruntime permission on Android 13+, and a notification channel (API 26+).MainActivityuses launch modeSingleTop/SingleTask, so taps on a notification arrive throughOnNewIntent.minSdkis 23. The current Firebase Messaging binding requires it, even though .NET 10's default is 21.shared_prefs/Ably_Device.xml. A backup restored onto a new phone would bring back another device's identity. The example should exclude theAbly_*files in its backup rules (dataExtractionRules/fullBackupContent), and the docs should tell apps to do the same. See row 21.3.3 Useful commands
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
.p8)..p8to the Ably test app (S1), with topic = bundle id. Use the sandbox APNs environment for development builds.iosandmauiworkloads4.2 Development-time manual work (part of the iOS package and example estimates)
AppDelegate : MauiUIApplicationDelegate. MAUI lifecycle events do not expose the APNs callbacks, so these methods must be overridden in it:RegisteredForRemoteNotificationsFailedToRegisterForRemoteNotificationsDidReceiveRemoteNotificationAlert | Badge | Sound. 1.x asked forSoundtwice and neverBadge.Entitlements.plisthasaps-environment = development.Info.plisthasUIBackgroundModes = remote-notification.4.3 Simulator vs device
xcrun simctl push <device> <bundle-id> payload.apns, or dragging a.apnsfile 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.4.4 Useful tools
content-available(silent) pushes. Low Power Mode also throttles them.4a. Both engineers
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:Push.Activate()POST_NOTIFICATIONS/ iOS authorisation). Token obtained. RSH3 reachesWaitingForNewPushDeviceDetails.ActivatedCallbackfires. Device listed in push admin with the correctplatform(android/ios),formFactorand token type (fcm/apns).channel.Push.SubscribeDevice()→ListSubscriptions()→SubscribeClient()→ unsubscribe bothOnMessageReceived/ iOSWillPresentNotificationfires. The example shows the payload.content-available: 1(iOS)OnMessageReceivedruns in the background. iOSDidReceiveRemoteNotificationruns, subject to iOS throttling (note this, not a failure).extras.pushextras.pushviaNotificationsPublisher.GotPushDeviceDetails). Push admin shows the new token and pushes still arrive.Push.Deactivate()→ push →Push.Activate()→ pushDeactivatedCallbackfires, the device is removed from push admin, and no push arrives. After re-activating, delivery works again.Ably.PubSub.Server:Push.Admin.PublishAsyncto the device id and client id.DeviceRegistrations.GetAsync/List. Repeat withClientOptions.PushAdminFullWait = true.fullWait=truemakes the server wait for completion before responding).BadDeviceToken. This confirms the docs on sandbox vs production.PushNotifications.mdand the example README from scratch5a. Out of scope for this testing
6. Results template (per release)
7. Effort summary (manual work only)
Not included:
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
sacOO7 commentedon Oct 21, 2026
@maratal had done push api testing for both
iOSandandroidforably-cli. Once I update the code, I might need to work with @maratal for testing the same behaviour using new dotnet MAUI push code.sacOO7 commentedon Oct 26, 2026
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?
PushRealtime.Activate/Deactivate,IRealtimeChannel.Pushandclient.Devicesaying that device push-receive isn't available in the 2.0 packages, with a link toPushNotifications.md. Push admin (client.Push.Admin) is unaffected.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.Pushandclient.Deviceare null without a mobile device, but they will be once the port lands:PushChannel.cs#L41(also L66, L92, L123, L159) says "callPubSubHttpClient.Push.Activate()", butPushHttphas noActivate.LocalDevice.cs#L140namesAndroidMobileDevice.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.