Использование Google Firebase Cloud Messages (FCM) в проектах

👁 45 просмотров

Firebase Cloud Messaging (FCM) — это межплатформенное решение для обмена сообщениями, которое позволяет надежно доставлять сообщения без каких-либо затрат. Используя FCM, вы можете уведомить клиентское приложение о том, что для синхронизации доступны новые электронные или другие данные.

Статья состоит из 2 частей. В первой рассматривается введение и начальная настройка, а далее подробно раскрывается принцип отправки и обработки уведомлений FCM.

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

👁 126 просмотров

Это перевод и дополнение официальной статьи по плагину 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 приведен ниже и еще ниже описаны параметры, которые входят в эту строку.

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

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

 

Часть 1. Push — уведомления для Android и iOS при помощи Firebase Cloud Messages

👁 119 просмотров

 

Это простой прямой подход, касающийся того, как реализовать push-уведомление в Android, а также iOS, используя плагин  cordova plugin for fcm для проекта Cordova и Google Firebase FCM в виде облачного сервера обработки сообщений.

Использование FCM в платформе Android

1. Создание проекта Cordova. Сначала необходимо иметь какой-то проект Cordova с добавленной платформой Android:

cordova create pushSample
cd pushSample
cordova platform add android

далее к этому проекту мы добавляем плагин cordova-plugin-fcm командой:

cordova plugin add cordova-plugin-fcm

В процессе установки данного плагина система нам выведет ряд ошибок, к примеру, скажет, что у нас отсутствует файл google-services.json:

Error: cordova-plugin-fcm: You have installed platform android but file 'google-services.json' was not found in your Cordova project root folder.
Note : This is because we have not added the google-services.json file which has to be created in the next following steps.

данный файл мы должны скачать из консоли Google Firebase в процессе создания приложения и находиться он должен в корневой директории проекта Cordova.

2. Создание облачного проекта Firebase. В консоли google firebse console жмем на кнопку «Добавить» и создаем новое облачный проект для Android, iOS и WEB — проектов:

После нажатия на кнопку «Создать проект» следующим шагом является добавление возможности создания облачных уведомлений через Firebase Cloud Messages и для этого необходимо нажать на пункту «Notifications» и далее следующее окно предложит ввести данные приложения для Android или iOS:

На данном этапе нажимаем на Android и заполняем данные и выйдет окно, требующий заполнения уникального идентификатора:

далее жмем на кнопку «Зарегистрировать приложение» и мы попадем на шаг, где нам предлагают скачать вышеупомянутый файл google-services.json:

данный файл скачиваем и кидаем в корень проекта Cordova pushSample/google-service.json.

Далее жмем «Продолжить» и сервис предложит нам добавить некоторый код в файл сборки build.gradle, который находится в корне платформы Android по пути pushSample/platforms/android/build.gradle:

buildscript {
  dependencies {
    // Add this line
    classpath 'com.google.gms:google-services:3.2.0'
  }
}

В скрипте сборки плагина по пути pushSample/platforms/android/cordova-plugin-fcm/pushSample-FCMPlugin.gradle :

dependencies {
  // Add this line
  compile 'com.google.firebase:firebase-core:11.8.0'
}
...
// Add to the bottom of the file
apply plugin: 'com.google.gms.google-services'

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

google-services plugin could not detect any version for com.google.android.gms or com.google.firebase, default version: 9.0.0 will be used.
please apply google-services plugin at the bottom of the build file.

Для решения можно написать костыли принудительного исполнения, прописав их в файл pushSample/platforms/android/build.gradle:

...

allprojects {
    repositories {
        ...
        configurations.all {
            resolutionStrategy {
                // Add force (11.4.0 is version you want to use)
                force 'com.google.firebase:firebase-messaging:11.4.0'
                force 'com.google.firebase:firebase-core:11.4.0'
                force 'com.google.android.gms:play-services-gcm:11.4.0'
            }
        }
    }
}

...

3. Пишем первое уведомление. После добавления кода построения сервисов Google облачный проект предложит нам отправить сообщение:

Перед тем, как написать новое сообщение из консоли в клиентские приложения в виде уведомлений необходимо сначала написать клиентский код, который будет их принимать. Для этого в папке скриптов создаем новый файл www/scripts/script.fcm.js, в котором будем писать код, выполняемый после инициализации всех ресурсов Cordova:

var app = {
    initialize: function() {
        this.setup();
    },
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
    },
    onDeviceReady: function() {
        app.receivedEvent('deviceready');
    },
    receivedEvent: function(id) {
        console.log('Received Event: ' + id);
    },
    setup: function() {  
        //***********Начало кода FCM
        //Функция обработки всех уведомлений, как в бакграунде, так и при открытом приложении
        FCMPlugin.getToken(function(token) {
            //this is the fcm token which can be used
            //to send notification to specific device 
            console.log(token);
            //FCMPlugin.onNotification( onNotificationCallback(data), successCallback(msg), errorCallback(err) )
            //Here you define your application behaviour based on the notification data.
            FCMPlugin.onNotification(function(data) {
                console.log(data);
                //data.wasTapped == true means in Background :  Notification was received on device tray and tapped by the user.
                //data.wasTapped == false means in foreground :  Notification was received in foreground. Maybe the user needs to be notified.
                if (data.wasTapped) {
                     //Notification was received on device tray and tapped by the user.
                     alert(JSON.stringify(data));
                 } else {
                     //Notification was received in foreground. Maybe the user needs to be notified.
                     alert(JSON.stringify(data));
                 }
            });
        });
        //************Конец кода FCM
    }
};

app.initialize();

Данный файл подключаем ко всем необходимым страницам нашего проекта Cordova. построим приложение и запустим на эмулятор или на реальное устройство:

cordova build android
cordova run android

И далее и консоли отправляем наше первое уведомление:

жмем на «Отправить сообщение» и ждем его в приложении в виде уведомления, причем, приложение может быть закрыто и уведомление все равно придет и будет видно в верхней части экрана устройства или эмулятора:

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