Оценок пока нет Часть 2. Принцип работы отправки и приемки уведомлений в Firebase Cloud Messages (FCM)

Это перевод и дополнение официальной статьи по плагину cordova-plugin-fcm.

Установка

Процесс установки мы уже рассматривали в первой части статьи. Перед началом, убедитесь, что у вас есть google-services.json для Android или GoogleService-Info.plist для iOS в корневой папке вашего проекта Cordova. Вам не нужно настраивать что-либо еще, чтобы иметь push-уведомление, работающее для обеих платформ, все это волшебство. Установка плагина FCM занимает не много времени

cordova plugin add cordova-plugin-fcm

Файлы конфигурации Firebase

Получите необходимые файлы конфигурации для Android или iOS из Firebase Console (см. документацию: https://firebase.google.com/docs/).

Детали компиляции под Android

Поместите загруженный файл «google-services.json» в корневую папку проекта Кордовы. Вам нужно будет убедиться, что вы установили соответствующие библиотеки Android SDK.

Если хотите добавить значок уведомления в Android> 5.0, то вы должны поместить картинку со значком с именем «fcm_push_icon.png» в папку «res» так же, как вы добавляете другие значки приложений. Если вы не установите этот ресурс, SDK будет использовать значок по умолчанию для вашего приложения, который может не соответствовать стандартам для Android> 5.0.

Детали компиляции под iOS

Поместите загруженный файл «GoogleService-Info.plist» в корневую папку проекта Cordova.

Использование FCM в Cordova

Пример заполнения JSON данных для отправки на сервер FCM по REST API представлен в ниже в подразделе Отправить уведомление. Пример из песочницы (REST API).

Настоятельно рекомендуется использовать REST API для отправки push-уведомлений, потому что консоль Firebase не имеет всех функций. Обратите внимание на пример в песочнице, чтобы научиться правильно использовать плагин. Вы также можете протестировать свои уведомления на бесплатном сервере тестирования: https://cordova-plugin-fcm.appspot.com.

Получение обновления токена

Токен — это идентификатор, выданный серверами соединения FCM, в клиентское приложение, который позволяет приложению получать сообщения. Обратите внимание, что регистрационные токены должны храниться в секрете.

//FCMPlugin.onTokenRefresh( onTokenRefreshCallback(token) );
/**
 * Обратите внимание, что этот Callback будет срабатывать каждый раз, 
 * когда будет сгенерироваться новый токен, в том числе и первый раз.
 */
FCMPlugin.onTokenRefresh(function(token){
    alert( token );
});

При первом запуске вашего приложения FCM SDK генерирует регистрационный токен для экземпляра клиентского приложения. Если вы хотите настроить таргетинг на отдельные устройства или создать группы устройств, вам необходимо получить доступ к этому токену или токенам.

Получение токена

Функция getToken возвращает токен текущего устройства или нулевое значение, если токен еще не установлен для устройства.

//FCMPlugin.getToken( successCallback(token), errorCallback(err) );
/**
 * Имейте в виду, то функция возвращает нулевое значение, 
 * если токен не был установлен еще.
 */
FCMPlugin.getToken(function(token){
    alert(token);
});

Подписаться на тему(топик)

//FCMPlugin.subscribeToTopic( topic, successCallback(msg), errorCallback(err) );
/**
 * Все устройства подписаны автоматически, 
 * ко 'всем' - и 'ios' и 'android' темам соответственно.
 * Должен соответствовать следующему регулярному выражению: "[a-zA-Z0-9-_.~%]{1,900}"
 */
 FCMPlugin.subscribeToTopic('topicExample');

Отписаться от темы(топика)

//FCMPlugin.unsubscribeFromTopic( topic, successCallback(msg), errorCallback(err) );
FCMPlugin.unsubscribeFromTopic('topicExample');

Получение данных push-уведомлений

Функция FCMPlugin.onNotification(…) принимает все уведомления, по токену или по топику, на который подписаны пользователи

//FCMPlugin.onNotification( onNotificationCallback(data), successCallback(msg), errorCallback(err) )
/**
 * Здесь Вы можете определить свое поведение приложения на основе данных уведомления.
 */
 FCMPlugin.onNotification(function(data){
    if(data.wasTapped){
      //Уведомление было получено в трей устройства и постучал пользователю.
      alert( JSON.stringify(data) );
    }else{
      //Уведомление было получено на переднем плане. Возможно, пользователя нужно уведомить.
      alert( JSON.stringify(data) );
    }
});

Следует отметить, что если вы используете Vue.js, как программную архитектуру или jQuery, то необходимо дождаться, пока ресурсы устройства подгрузятся, иначе можно получить ошибку, что плагин FCMPlugin не определен. Один из вариантов — размещение обработчика в setTimeout

var app = {
    initialize: function() {
        this.bindEvents();
        this.setupApp();
    },
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
    },
    onDeviceReady: function() {
    },
    setupApp: function() {
        //Программная логика на какой-то библиотеке
        setTimeout(function(){
            FCMPlugin.onNotification(function(data) {
                console.log(data);
            });
        },2000);
    }
}

app.initialize();

или разместить весь код в обработчике события deviceready

var app = {
    initialize: function() {
        this.bindEvents();
        this.setupApp();
    },
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
    },
    onDeviceReady: function() {
        FCMPlugin.onNotification(function(data) {
            console.log(data);
        });
    },
    setupApp: function() {
        //Программная логика на какой-то библиотеке
    }
}

app.initialize();

Отправить уведомление. Пример из песочницы (REST API)

Чтобы отправлять FCM — уведомления тому или иному устройству нам необходимо знать токен этого устройства и тему (топик), на который подписано устройство.

Как получить токен, подписаться устройство на тему(топик) и как отписаться мы выше уже привели примеры с кодом. Теперь нам осталось уметь отправлять уведомления и как мы уже говорили выше, для этого нужно отправлять JSON — с заполненными данными методом POST на адрес https://fcm.googleapis.com/fcm/send и потребуется указать еще 2 заголовка отправки, как Content-Type: application/json и Authorization: key=AIzaSy*******************. Первый заголовок указывает, что мы передаем JSON — данные и второй — что, запрос содержит учетные данные для аутентификации пользовательского агента с сервером. Второй заголовок принимает параметр ключа API для веб-приложения, который можно узнать в консоли FCM

 

Пример этой JSON приведен ниже и еще ниже описаны параметры, которые входят в эту строку.

Дополнительно:

• Полная документация: https://firebase.google.com/docs/cloud-messaging/http-server-ref
• Бесплатный сервер тестирования: https://cordova-plugin-fcm.appspot.com

{
  "notification":{
    "title":"Notification title",
    "body":"Notification body",
    "sound":"default",
    "click_action":"FCM_PLUGIN_ACTIVITY",
    "icon":"fcm_push_icon"
  },
  "data":{
    "param1":"value1",
    "param2":"value2"
  },
    "to":"/topics/topicExample",
    "priority":"high",
    "restricted_package_name":""
}

Метод передачи и заголовки с параметрами:

• POST: https://fcm.googleapis.com/fcm/send
• HEADER: Content-Type: application/json
• HEADER: Authorization: key=AIzaSy*******************

Передаваемые параметры в JSON методом POST:

• sound — необязательный параметр для указания своего звука уведомления
• click_action — должен присутствовать с указанным значением для Android
• icon — значок — имя ресурса для Android >5.0
• data — положите любые «param»:»value» и получите их в JavaScript callback — уведомлениях
• to — токен устройства или /topic/topicExample
• priority — должен быть установлен в «high» для доставки уведомлений закрытым iOS — приложениям
• restricted_package_name — Необязательное поле, если вы хотите отправить только на ограниченный пакет приложений (т.е.: com.myapp.test)

Пример отправки POST — запроса FCM — уведомления при помощи jQuery

В коде представлен пример AJAX запроса методом POST с указанием необходимых заголовков и их параметров

var fcm_server_key = "AIzaSy*******************";

$.ajax({
  method: "POST",
  dataType: 'json',
  headers: {'Content-Type': 'application/json', 'Authorization': 'key=' + fcm_server_key},
  url: "https://fcm.googleapis.com/fcm/send",
  data: JSON.stringify(
      {
        "notification":{
          "title":"Title",  //Любое значение
          "body": "Body",  //Любое значение
          "sound": "default", //Если вы хотите звучание в уведомление
          "click_action": "FCM_PLUGIN_ACTIVITY",  //Должен присутствовать для Android
          "icon": "fcm_push_icon"  //Белая иконка ресурса Android
        },
        "data":{
          "param1":"value1",  //Любые данные, получаемые в callback - уведомлении
          "param2": "Prueba"
        },
        "to":"/topics/all", //Тема(топик) или какое-то одно устройство
        "priority":"high", //Если не установлен, то уведомления не могут быть доставлены для закрытых приложений iOS
        "restricted_package_name":"" //Необязательно. Устанавливается для фильтрации приложений
      }
    )
}).success(function(data){
  alert("Success: " + JSON.stringify(data));
}).error(function(data){
  alert("Error: " + JSON.stringify(data));
});

Пример отправки POST — запроса FCM — уведомления при помощи cURL с сервера

Вот пример cURL. Не забудьте заменить авторизацию заголовка собственной учетной записью службы Firebase

curl -X POST \
  https://fcm.googleapis.com/fcm/send \
  -H 'authorization: key=YOUR-FIREBASE-SERVER-KEY' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
	"to": "/topics/all",
	"notification": {
	    "title": "Hello World!",
	    "body": "Proin rutrum, nunc vitae porta volutpat, mi nibh.",
        "icon": "fcm_push_icon",
    	"color": "#F79838",
        "sound":"default"
	},
	"priority": "high",
        "click_action":"FCM_PLUGIN_ACTIVITY"
}'

 

Пример отправки POST — запроса FCM — уведомления при помощи Axios из устройства

Axios — это отличная клиентская библиотека, которая использует промисы по умолчанию, а так же работает как на сервере(что делает его подходящим для получения данных при рендеринге на сервере), так и на клиенте. Axios очень легко начать использовать с Vue.js. Поэтому, если у вас приложение написано с использованием Vue.js или Ionic, то отправку уведомлений нам придется реализовать через Axios

var fcm_server_key = "AIzaSy*******************";

axios({
  method: 'POST', //Метод отправки
  url: 'https://fcm.googleapis.com/fcm/send',
  data: JSON.stringify(
      {
        "notification":{
          "title":"Title",  //Любое значение
          "body": "Body",  //Любое значение
          "sound": "default", //Если вы хотите звучание в уведомление
          "click_action": "FCM_PLUGIN_ACTIVITY",  //Должен присутствовать для Android
          "icon": "fcm_push_icon"  //Белая иконка ресурса Android
        },
        "data":{
          "param1":"value1",  //Любые данные, получаемые в callback - уведомлении
          "param2": "Prueba"
        },
        "to":"/topics/all", //Тема(топик) или какое-то одно устройство
        "priority":"high", //Если не установлен, то уведомления не могут быть доставлены для закрытых приложений iOS
        "restricted_package_name":"" //Необязательно. Устанавливается для фильтрации приложений
      }
    ),
  headers: {
    'Content-Type': 'application/json', 'Authorization': 'key=' + fcm_server_key
  }
}).then((response) => {
    console.log(response)
})
.catch((error) => {
    console.log(error)
});
    

Пример отправки POST — запроса FCM — уведомления при помощи Axios из Node.js

Для начала нам потребуется установить Axios в систему при помощи простой команды через менеджер модулей npm

npm install axios

Теперь создаем index.js в корневом каталоге вашего проекта и заполняем его следующим образом

var axios = require('axios');
const fcmKey = 'YOUR_FCM_SERVER_KEY'
const fcmUrl = 'https://fcm.googleapis.com/fcm/send'
const phoneToken = 'MY_PHONE_TOKEN'

Здесь мы просто импортируем модуль axios, устанавливаем ключ сервера api и указываем адрес сервера взаимодействия, на который мы отправляем POST наши уведомления. Константа phoneToken является идентификатором вашего телефона, который раздается клиентам сервером FCM для регистрации в системе обмена.

Чтобы наше уведомление отвечало на событие, мы заставим его прослушивать конечную точку тестирования в базе данных Firebase

ref.child('test').on('child_added', (snapshot) => {
  const notification = buildNotification(snapshot.val())
  sendNotification(notification)
})

Как вы можете видеть, это просто наблюдает за конечной точкой/тестом(endpoint /test) для нового потомка. Потомок — это просто ключ/значение(key/value) с ключом «name». Перейдем к нашей функции buildNotification()

function buildNotification (data) {
  const { name } = data
  return {
    "notification": {
      "title":"New name",
      "text":`${name} is awesome`,
      "sound":"default"
    },
    "to":phoneToken,
    "priority":"high"
  }
}

Не забудьте установить приоритет на высокий уровень при разработке, иначе может потребоваться некоторое время, прежде чем ваше уведомление поступит

function buildRequest (notification) {
  return {
    url: fcmURL,
    method: 'post',
    headers: {
      "Content-Type":"application/json",
      "Authorization":`key=${fcmKey}`
    },
    data: notification
  }
}
function sendNotification(notification) {
  const request = buildRequest(notification)
axios(request).then((r) => {
    console.log(r)
  }).catch((error) => {
    console.log(error)
  })
}

Сначала мы создаем запрос с нашим уведомлением и токеном FCM в заголовках запросов. Затем мы передаем этот запрос в Axios и слушаем ответ или ошибку. Теперь вы должны увидеть уведомление, появившееся на вашем устройстве.

Если у вас не получилось, то есть несколько вещей, на которые стоит обратить внимание:

• Убедитесь, что приоритет установлен на высокий
• Убедитесь, что у вас есть сертификат push-уведомления, загруженный в консоль Firebase (В iOS 10 могут быть изменения на использование)

Как это работает

К примеру, мы отправляем push-уведомление на одно устройство или в тему(топик). При этом возможны 2 случая:

a. Приложение находится на переднем плане:

• Данные уведомления принимаются в Callback — вызове JavaScript без сообщения в панели уведомлений (это обычное поведение push — уведомлений в мобильных ).

b. Приложение находится в фоновом режиме или закрыто:

• Устройство отображает сообщение уведомления на панели уведомлений устройства.
• Если пользователь удаляет уведомление, приложение выходит на передний план и данные уведомления принимаются в Callback —  вызове JavaScript.
• Если пользователь не обращается к уведомлению, но открывает приложение, то ничего не происходит до тех пор, пока уведомление не будет обработано.

Реальный пример отправки из Axios

Код отправки уведомления

/**
 * to - кому и куда отправляется уведомление и может быть:
 * 1. токеном
 * 2. топиком
 * 3. или можем отправить всем сразу
 * title - заголовок уведомления
 * message - тело уведомления
 * apiKey - секретный ключ из облачного приложения Android Google FCM
 */
var to =  "cicx9RtKXdk:APA91bGsk16she-DPkwjSrM5_9ZfJ4v189k53ETUF081DXtIH6vl6MwsSy8ky6Orn5MUzZJqzUoCNHOZ3BxWquTvIJis2X5zzFtJQSY6ozQFUsMb6157lKS27HTDN4vuMcF4_CuTpEJH";          
//var to = "/topics/topicExample";
//var to = "/topics/all";

var title = "Новое сообщение";
var message = "Мое сообщение!";
var apiKey = "AIzaSyDqYOMoJ1jVoIfLTErYboDOtuqfCHcnWfE";

axios({
method: 'POST', //Метод отправки
url: 'https://fcm.googleapis.com/fcm/send', 
data:{
    "notification":{
      "title":title,  //Любое значение
      "body": message,  //Любое значение
      "sound": "default", //Если вы хотите звучание в уведомление
      "click_action": "FCM_PLUGIN_ACTIVITY",  //Должен присутствовать для Android
      "icon": "fcm_push_icon"  //Белая иконка ресурса Android
    },
    "data":{
      "param1":"value1",  //Любые данные, получаемые в callback - уведомлении
      "param2": "Prueba"
    },
    "to":to,
    "priority":"high" //Если не установлен, то уведомления не могут быть доставлены для закрытых приложений iOS
    //"restricted_package_name":"" //Необязательно. Можно закомментить
},
headers: {
    'Content-Type': 'application/json', 'Authorization': 'key=' + apiKey
}
}).then((response) => {
console.log(response)
})
.catch((error) => {
console.log(error)
});

Код приемки уведомления. Необходимо ждать, пока подгрузяться ресурсы

setTimeout(function(){
    if(data.wasTapped){
      //Уведомление было получено в трей устройства и постучал пользователю.
      alert( JSON.stringify(data) );
    }else{
      //Уведомление было получено на переднем плане. Возможно, пользователя нужно уведомить.
      alert( JSON.stringify(data) );
    }
},2000);

или можно закинуть в обработчик Cordova ‘deviceready’

var app = {
    initialize: function() {
        this.bindEvents();
        this.setupApp();
    },
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
    },
    onDeviceReady: function() {
        FCMPlugin.onNotification(function(data) {
            console.log(data);
        });
    },
    setupApp: function() {
        //Программная логика на какой-то библиотеке
    }
}

app.initialize();