App Center Push


Please note this feature is being retired. For more information, please see the blog post. For more information, refer to the Push Migration Guide.


Starting with version 1.11.0, calling Push.DidReceiveRemoteNotification(...) within a UNUserNotificationCenterDelegate is no longer necessary for iOS applications. If you implemented a UNUserNotificationCenterDelegate and are calling the Push.DidReceiveRemoteNotification(...) callback, please refer to the App Center SDK migration guide to migrate your code.

App Center Push enables you to send push notifications to users of your app from the App Center portal.

Prerequisite - Perform platform-specific setup

Push notifications work differently on UWP, iOS, and Android, therefore, before the shared APIs can be leveraged in Xamarin.Forms, you need to perform some setup on each platform. Follow the instructions for integrating push with each of the platform-specific setup guides for Push, and then return here.

Setup Guides


Even if you only access the AppCenter or Push class from your shared or PCL project, the App Center NuGet packages must be added to each platform-specific project.

Add App Center Push to your app

Follow the Get started section if you haven't set up and started the SDK in your application yet.

1. Add the App Center Push module

Visual Studio for Mac

  • Open Visual Studio for Mac.
  • Click File > Open and choose your solution.
  • In the solution navigator, right click the Packages section, and choose Add NuGet packages....
  • Search for App Center, and install App Center Push.
  • Click Add Packages.

Visual Studio for Windows

  • Open Visual Studio for Windows.
  • Click File > Open and choose your solution.
  • In the solution navigator, right-click References and choose Manage NuGet Packages.
  • Search for App Center, and install Microsoft.AppCenter.Push.

Package Manager Console

  • Open the console in Visual Studio. To do this, choose Tools > NuGet Package Manager > Package Manager Console.
  • If you're working in Visual Studio for Mac, make sure you have NuGet Package Management Extensions installed. For this, choose Visual Studio > Extensions, search for NuGet and install, if necessary.
  • Type the following command in Package Manager Console:
Install-Package Microsoft.AppCenter.Push


If you use the App Center SDK in a portable project (such as Xamarin.Forms), you must install the packages in each of the projects: the portable, Android, and iOS ones. To do that, you should open each sub-project and follow the corresponding steps described in Visual Studio for Mac or Visual Studio for Windows sections.


If your Android project does not target the Mono framework version 9.0 or higher, you will not be able to install the package. You can safely bump this version in Options > General > Target framework as this has no impact on minimum API level or target API level fields.

2. Start App Center Push

In order to use App Center, you must opt in to the module(s) that you want to use. By default no modules are started and you will have to explicitly call each of them when starting the SDK.

Add the following using statement to the top of the file you are referencing Push from:

using Microsoft.AppCenter.Push

Next, add typeof(Push) to your AppCenter.Start() method to start App Center Push.

AppCenter.Start("{Your App Secret}", typeof(Push));

Make sure you have replaced {Your App Secret} in the code sample above with your app secret.

Intercept push notifications

App Center Push makes it possible to intercept push notifications but there is some additional setup required to enable this feature in platform-specific projects.

iOS additional steps


You only need this step if you disabled method swizzling while setting up Xamarin.iOS.

To enable the push event feature, implement DidReceiveRemoteNotification in your AppDelegate class as follows:

public override void DidReceiveRemoteNotification(UIApplication application, NSDictionary userInfo, System.Action<UIBackgroundFetchResult> completionHandler)
	var result = Push.DidReceiveRemoteNotification(userInfo);
	if (result)

Android additional steps

Launch mode

If (and only if) your launcher activity uses a launchMode of singleTop, singleInstance or singleTask, you need to add this in the activity's OnNewIntent method:

        protected override void OnNewIntent(Android.Content.Intent intent)
            Push.CheckLaunchedFromNotification(this, intent);

Splash screen activity

This section applies if you have a Splash Screen activity (or a similar concept) that starts the main activity and main activity is the one creating the forms application.

When you click on the push notification if the application is not launched, the push information are intent extras in the launcher activity which is the splash screen. This intent needs to be copied to the main activity if the SDK is initialized in the main activity in order to process that information.

The simplest way of doing that is to locate the code where you start your main activity from the launcher activity:

    // Most apps have this
    StartActivity(new Intent(this, typeof(MainActivity)));

And modify it like this:

    var intent = new Intent(this, typeof(MainActivity));
    if (Intent.Extras != null)
        intent.PutExtras(Intent.Extras); // copy push info from splash to main

UWP additional steps

To enable the push event feature, modify your UWP application's OnLaunched method to include Push.CheckLaunchedFromNotification(e); at the end as follows:

protected override void OnLaunched(LaunchActivatedEventArgs e)
    // ... not showing entire long method ...
    if (e.PrelaunchActivated == false)
        if (rootFrame.Content == null)
            // This is what triggers Xamarin.Forms portable App.OnStart method where you typically call AppCenter.Start
            rootFrame.Navigate(typeof(MainPage), e.Arguments);

    // Best place to call this method

    // End of method

Subscribe to the push event

You can subscribe to the Push.PushNotificationReceived event to be notified whenever a push notification is received in the foreground or a background push notification has been clicked by the user.

The behavior of the event depends on:

  • The platform (iOS vs Android vs UWP).
  • Whether the push is received while application is in foreground or background.

For all platforms, when the push is received in background, the event is not fired right away, the user will first see an Android system notification, an iOS alert, or a UWP toast.

The event is fired only by clicking the notification in that case.

When the push is received in foreground, the event is fired right away but no notification is shown to user.


When the push is clicked from background on Android and UWP, the event does not have title and message in the event arguments, only iOS expose those fields for all events.


On iOS only, if silent notifications are enabled and you push a notification with content-available: 1, then the event may be triggered twice for the same notification: when the notification is received in background and when it is tapped.

The following example demonstrates how to use the push event.

// This should come before AppCenter.Start() is called
// Avoid duplicate event registration:
if (!AppCenter.Configured)
    Push.PushNotificationReceived += (sender, e) =>
        // Add the notification message and title to the message
        var summary =  $"Push notification received:" +
                            $"\n\tNotification title: {e.Title}" +
                            $"\n\tMessage: {e.Message}";
        // If there is custom data associated with the notification,
        // print the entries
        if (e.CustomData != null)
            summary += "\n\tCustom data:\n";
            foreach (var key in e.CustomData.Keys)
                summary += $"\t\t{key} : {e.CustomData[key]}\n";

        // Send the notification summary to debug output

// AppCenter.start after
AppCenter.Start(..., ... ,typeof(Push), ...);

Custom Data in your notifications

You can send optional custom data as part of the push payload. The data will be sent in the key-value format. This custom data can be intercepted in the app through Push SDK callback.

There are few reserved keywords in each platform that can be set via custom data:


  • color: The notification's icon color, expressed in #rrggbb format. Will be applied only on devices with Android 5.0 and later.
  • icon: The notification's icon. You should specify name of the icon resource. Supports drawable and mipmap types. If this value isn't specified application icon will be used. See Status Bar Icons on Android Developers for details regarding the icon specifications.
  • sound: Add this key when you want to play a sound when the device receives the notification. Supports default or the filename of a sound resource bundled in the app. Sound files must reside in /res/raw/. This is effective only for devices running or targeting an Android version lower than 8. Sound is set by default on Android 8 and user can change notification settings for the group of notifications coming from AppCenter.

Configure notification's default values


Please note this feature is being retired. For more information, please see the blog post. For more information, refer to the Push Migration Guide.

You can specify custom defaults for the icon and color that gets applied when it isn't set in the push payload.

The lines below should be added to AndroidManifest.xml inside the application tag:

<!-- Set default notification icon and color. -->
    android:resource="@drawable/ic_notification" />
    android:resource="@color/notification" />

App Center displays the application icon if a custom default icon and an icon are not set in the push payload.


  • badge: Add this key when you want to modify the badge of your app icon. If this key is not included, the badge is not changed. To remove the badge, set the value of this key to 0.
  • sound: Add this key when you want to play a sound. The value of this key is the name of a sound file in your app's main bundle or in the Library/Sounds folder of your app’s data container. If the sound file cannot be found, or if you specify default for the value, the system plays the default alert sound.
  • content-available: Add this key with a value of 1 to configure a silent notification. When this key is present, the system wakes up your app in the background and delivers the notification to its app delegate. For information about configuring and handling silent notifications, see Configuring a Silent Notification.
  • mutable-content: Add this key with a value of 1 to enable media attachments. The application needs to support a service extension to download and handle the attachment content. For more information you can refer to Apple documentations.


  • audio: Add this key when you want to play a sound. this will modify the audio attribute for toast notifications.
  • image: Add this key when you want to modify the image attribute for tile and toast notifications.

Enable or disable Push at runtime

You can enable and disable App Center Push at runtime. If you disable it, the SDK will stop updating the registration identifier that is used to push notifications, but the existing one will continue to work. In other words, disabling the App Center Push in the SDK will NOT stop your application from receiving push notifications.


To enable App Center Push again, use the same API but pass true as a parameter.


You don't need to await this call to make other API calls (such as IsEnabledAsync) consistent.

The state is persisted in the device's storage across application launches.


This method must only be used after Push has been started.

Check if App Center Push is enabled

You can also check if App Center Push is enabled or not:

bool isEnabled = await Push.IsEnabledAsync();


This method must only be used after Push has been started, it will always return false before start.