App Center Push

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

Prerequisite - Enable Apple Push Notifications service (APNs) for your app

Please configure Apple Push Notifications service (APNs) for your app from your Apple developer account and the App Center portal before adding App Center Push to your app. App Center Push won't get any notifications if you don't setup push notifications.

Enable push notifications on your application

Double-click the Entitlements.plist file in your Xamarin Solution Explorer. This will open the Entitlements.plist editor. Check the Enable Push Notifications checkbox from the Push Notifications section. enable-push-capability

Set up APNs

Log in to the App Center portal, select your application, click on the Push button from the left menu then click Next to reveal the push notification settings UI:

app-center-push-settings

  • On the bottom of the page, select Sandbox for initial development or Production for production version of your application.

  • Collect the following information:

    1. Prefix and ID

      • Go to your Apple developer account and select your application from the App ID list in Identifiers.

      • Copy the Prefix value from this window and paste it to the App Center push settings.

      • Do the same with the ID value.

      apple-dev-center-app-id

    2. Key ID

      • In your Apple developer account create a new key in Certificates, Identifiers & Profiles/Keys.

      • Make sure to check the APNs checkbox.

      • Fill in the key name

      • Press Continue then Confirm.

      apple-dev-center-new-auth-key

      • On the next screen, copy the Key ID value and paste it to the App Center push settings.

      • Download the key file.

      apple-dev-center-confirm-auth-key

    3. Push Token

      • Open your key file with a text editor and copy the authentication token it contains.

      auth-key-file

      • On the App Center push settings, paste this token to the Push Token field then click Done to complete this configuration.

For more information, refer to the Xamarin documentation.

[Optional] Enable silent notifications

Silent notifications give you a way to wake up your app so that it can refresh its data in the background (see Xamarin documentation). To enable silent notifications double-click the Info.plist file in your Xamarin Solution Explorer. This will open the Info.plist editor. Check Background modes then Remote notifications checkboxes from the Background modes section. enable-silent-notifications

Add App Center Push to your app

1. Add the App Center Push package

The App Center SDK is designed with a modular approach – a developer only needs to integrate the modules of the services that they're interested in. It can be integrated using Visual Studio or Package Manager Console.

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.

2. Start App Center Push service

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.

Note

If your Xamarin.iOS project is part of a Xamarin.Forms application, it is not necessary to add the call to AppCenter.Start() in the Xamarin.iOS 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

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

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
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);
};

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();

Disable automatic forwarding of application delegate's methods to App Center services

App Center uses swizzling to automatically forward your application delegate's methods to App Center services to improve SDK integration. There is a possibility of conflicts with other third party libraries or the application delegate itself. In this case, you might want to disable the App Center application delegate forwarding for all App Center services by following the steps below:

  1. Open your Info.plist file.
  2. Add AppCenterAppDelegateForwarderEnabled key and set the value to 0. This will disable application delegate forwarding for all App Center services.
  3. Implement two methods to register push notifications

    Implement the methods RegisteredForRemoteNotifications and FailedToRegisterForRemoteNotifications in your AppDelegate class as follows:

    public override void RegisteredForRemoteNotifications(UIApplication application, NSData deviceToken)
    {
        Push.RegisteredForRemoteNotifications(deviceToken);
    }
    
    public override void FailedToRegisterForRemoteNotifications(UIApplication application, NSError error)
    {
        Push.FailedToRegisterForRemoteNotifications(error);
    }
    

    Note

    You may have already imlemented these methods while following Xamarin's documentation on enabling APNS. It is okay to replace the implementation from their example with the code provided above. You may also add the App Center lines of code above alongside existing code in your implementation of these methods.

  4. Implement the callback to enable push event

    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)
        {
            completionHandler?.Invoke(UIBackgroundFetchResult.NewData);
        }
        else
        {
            completionHandler?.Invoke(UIBackgroundFetchResult.NoData);
        }
    }
    

Now, the Push.PushNotificationReceived event will be invoked when your application receives a push notification. This event is also accessible from the PCL part of a Xamarin.Forms project.