Push Notifications

Ionic Cloud has been deprecated. To continue using Ionic services, migrate to Ionic Pro before Jan. 31, 2018.


Push Notifications allow you to send messages, alerts, or other notifications to your users’ devices, even when your app is closed.

With Push you can:

  • Target Users
  • Schedule Notifications to be sent at a specific time
  • Send contextual content, such as a user name or custom user field
  • Automatically send notifications as users match criteria
  • Attach media to notifications
  • Trigger app events with background notifications



Plugin Installation

We use Phonegap’s push plugin to receive native push notifications on iOS and Android devices. When you install the plugin, you need to supply a SENDER_ID variable, which is your FCM Sender ID.

$ cordova plugin add phonegap-plugin-push --variable SENDER_ID=12341234 --save

Cloud Configuration

You also need to tell us your FCM Sender ID. Additionally, you may provide push plugin configuration under pluginConfig.

Fill in the following:

APP_ID Your app’s ID
const cloudSettings: CloudSettings = {
  'core': {
    'app_id': 'APP_ID',
  'push': {
    'sender_id': 'SENDER_ID',
    'pluginConfig': {
      'ios': {
        'badge': true,
        'sound': true
      'android': {
        'iconColor': '#343434'
.config(function($ionicCloudProvider) {
    "core": {
      "app_id": "APP_ID"
    "push": {
      "sender_id": "SENDER_ID",
      "pluginConfig": {
        "ios": {
          "badge": true,
          "sound": true
        "android": {
          "iconColor": "#343434"

Injecting Push

Import Push from the Cloud Client and specify it as a dependency in your component constructor.

import {Component} from '@angular/core';
import {
} from '@ionic/cloud-angular';

@Component( ... )
export class MyPage {
  constructor(public push: Push) {

Specify ionic.cloud as a dependency for your module. This gives you access to $ionicPush.

angular.module('myapp.controllers', ['ionic.cloud'])

.controller('MyCtrl', function($scope, $ionicPush) {

App Implementation

Registering Device Tokens

Before a device can receive native push notifications, it must be registered. It’s recommended to call register() every time the app is opened so the device is always registered and ready for notifications.

if you’re using auth, the best place to call register() is after calling login() so that the push token is saved to the authenticated user.

this.push.register().then((t: PushToken) => {
  return this.push.saveToken(t);
}).then((t: PushToken) => {
  console.log('Token saved:', t.token);
$ionicPush.register().then(function(t) {
  return $ionicPush.saveToken(t);
}).then(function(t) {
  console.log('Token saved:', t.token);

We store the generated device token with the current user when the token is saved. If you do not want them associated, you can pass the ignore_user option. See the saveToken() API docs for more info.


You can unregister a device from push notifications by calling unregister().

If you’re using Auth, the best place to call unregister() is before calling logout().

Handling Notifications

To handle push notifications in your app, you need to subscribe to the notification observable.

  .subscribe((msg) => {
    alert(msg.title + ': ' + msg.text);

To handle push notifications in your app, you need to listen to the cloud:push:notification event using angular’s $on.

$scope.$on('cloud:push:notification', function(event, data) {
  var msg = data.message;
  alert(msg.title + ': ' + msg.text);

Sending Pushes

You can create notifications in the Dashboard by navigating to Push › New Notification.

Alternatively, you can use this API endpoint to create push notifications.

Checking Notification Status

After your notification has been sent to the API, the notification status will be enqueued. This means we are doing background work such as collecting the appropriate recipients and sending them each individual push notification messages. Each message can have independent status, and you can check the status of each by using this API endpoint.

Background Notifications

iOS Background Notifications

To send an iOS background notification, you will need to send your notifications with the content-available flag enabled, which you will find in the Ionic Dashboard when you send a new Push.

In order to receive background push notifications, you must first enable Remote Notifications in your app.

Once you receive a background notification, you must handle it properly. On iOS, you have 30 seconds to handle a background notification or the OS will kill your app. You must use the push.finish() handler after you’re done processing the notification.

push.on('notification', function(data) {
    // do something with the push data
    // then call finish to let the OS know we are done
    push.finish(function() {
        console.log("processing of push data is finished");
    }, function() {
        console.log("something went wrong with push.finish for ID = " + data.additionalData.notId)
    }, data.additionalData.notId);


My requests against the API appear fine, but pushes aren’t delivered.

Check out the API docs for information about checking the status of a push notification. We provide a set of error codes to help you troubleshoot.

If the status is sent, then you could be experiencing one of the following:

Note for users of Xcode 8 and higher.

If you're using the latest version of Xcode, you will likely need to activate the Push Notifications capability before your app is able to receive notifications.

To do this, simply navigate to the Capabilities section in your app's overview within Xcode and toggle Push Notifications, as seen below.