App Center Push

Note

If you have integrated Push in earlier versions of the SDK, you can optionally remove Firebase SDK dependencies.

App Center Push enables you to send push notifications to users of your app from the App Center portal. App Center portal and the Push SDK is integrated with Firebase Cloud Messaging.

Note that only devices having the Google Play store application or emulators with Google APIs images can receive the notifications.

Note

A notification appears in the system notification center only if the application is in the background at the moment the Push is received.

Prerequisites

1. Connect your app to Firebase

Before using App Center Push service, you need to connect your application to Firebase. Please learn about Prerequisites.

2. Obtain your Android API Key and Sender ID

In the Firebase Console, go to Project Settings. Navigate to the Cloud Messaging tab. Copy the Server Key. This will be the Android API Key that you will need to set in the App Center Push portal. Also make a note of the Sender ID, as you will need it later.

3. Customize ProGuard configuration

If you use ProGuard, you have to customize its configuration for Push.

3.1. Create a ProGuard configuration file

Note

If you don't use ProGuard or if you already have a ProGuard configuration file in your project, you may skip this section.

Add an empty file to your Xamarin.Android project named proguard.cfg. Set the build action to "ProguardConfiguration."

proguard-configuration-build-action

3.2. Add customization to ProGuard configuration file

In your Xamarin.Android project, please add the following line to your proguard.cfg file:

-dontwarn com.microsoft.appcenter.push.**

Add App Center Push to your app

Please 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 or Xamarin Studio

  • Under your project, select Packages, open context menu and click Add packages.
  • Search for App Center, and select App Center Push.
  • Click Add Packages.

Visual Studio for Windows

  • Navigate to the Project > Manage NuGet Packages...
  • Search for App Center, then install Microsoft.AppCenter.Push.

Package Manager Console

  • Type the following command in Package Manager Console:

    PM> Install-Package Microsoft.AppCenter.Push

Note

If you use the App Center SDK in a portable project (such as Xamarin.Forms), you need to install the packages in each of the projects: the portable, Android, iOS and UWP ones.

3. Modify AndroidManifest.xml

Edit AndroidManifest.xml and insert the following permission before the <application> section:

<uses-permission android:name="${applicationId}.permission.C2D_MESSAGE" />
<permission android:name="${applicationId}.permission.C2D_MESSAGE" android:protectionLevel="signature" />

4. Start App Center Push

In order to use App Center, you need to opt in to the module(s) that you want to use, meaning 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 service.

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

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

Additionally, you need to set the Sender ID in your Xamarin.Android project (even if you are using Xamarin.Forms). This can be achieved with the following line of code:

Push.SetSenderId("{Your Sender ID}");

Make sure that you replace {Your Sender ID} with the Sender ID you obtained in the "Prerequisites" step. The method should be called before AppCenter.Start is called. This means that in a Xamarin.Forms project, it must go before the call to LoadApplication(new App()); in your Xamarin.Android project's OnCreate() method for the main Activity class.

Note

If your Xamarin.Android project is part of a Xamarin.Forms application, it is not necessary to add the call to AppCenter.Start() in the Xamarin.Android portion of the project. The method call can instead be made from the PCL or shared project portion of your Xamarin.Forms application.

Intercept push notifications

Additional setup

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

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

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.

Note

A notification is not generated when your application receives a push in the foreground.

Note

If the push is received in background, the event is NOT triggered at receive time. The event is triggered when you click on the notification.

Note

The background notification click callback does NOT expose title and message. Title and message are only available in foreground pushes.

The following example demonstrates how to use the push event.

// This should come before AppCenter.Start() is called
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
    System.Diagnostics.Debug.WriteLine(summary);
};

Existing Firebase Analytics users

App Center Push SDK automatically disables Firebase Analytics. If you are a Firebase customer and want to keep reporting analytics data to Firebase, you need to call Push.EnableFirebaseAnalytics() before AppCenter.Start() like so:

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

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 WNS 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.

Push.SetEnabledAsync(false);

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

Push.SetEnabledAsync(true);

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

Check if App Center Push is enabled

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

bool isEnabled = await Push.IsEnabledAsync();