Push Notifications

Summary

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

Prerequisites

Setup

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
SENDER_ID Your FCM Sender 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) {
  $ionicCloudProvider.init({
    "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 [email protected]/core';
import {
  Push,
  PushToken
} from [email protected]/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.

Unregistering

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.

this.push.rx.notification()
  .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.

FAQ

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.

Services

    API

      General