Как настроить сообщение на разных платформах

Firebase Admin SDK и FCM v1 HTTP API позволяют запросам сообщений задавать все поля, доступные в объекте message. К ним относятся:

  • общий набор полей, которые будут интерпретироваться всеми экземплярами приложения, получающими сообщение.
  • наборы полей для определенных платформ, например AndroidConfig и WebpushConfig, которые интерпретируются только экземплярами приложения, работающими на указанной платформе.

Блоки для определенных платформ позволяют настраивать сообщения для разных платформ, чтобы они правильно обрабатывались при получении. Сервер FCM учтет все указанные параметры и настроит сообщение для каждой платформы.

Когда использовать общие поля

Используйте общие поля, когда вы:

  • Отправка полей на любую платформу
  • Отправка сообщений в темы

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

Когда использовать поля для определенных платформ

Используйте поля для определенных платформ, если вы хотите:

  • Как отправлять поля только на определенные платформы
  • Отправлять поля, относящиеся к определенной платформе, в дополнение к общим полям.

Если вы хотите отправлять значения только на определенные платформы, используйте поля для конкретных платформ. Например, чтобы отправить уведомление только на платформы Apple и Web, но не на Android, необходимо использовать два отдельных набора полей: один для Apple и один для Web.

Если вы отправляете сообщения с определенными параметрами доставки, используйте для их настройки поля, относящиеся к конкретной платформе. При желании вы можете указать разные значения для каждой платформы. Однако даже если вы хотите задать одно и то же значение на разных платформах, вам нужно использовать поля, предназначенные для каждой из них. Это связано с тем, что каждая платформа может интерпретировать значение по-разному. Например, на Android время жизни задается как срок действия в секундах, а на Apple – как дата окончания срока действия.

Уведомление с параметрами доставки для конкретной платформы

В следующем запросе на отправку HTTP v1 API отправляет общий заголовок и контент уведомления на все платформы, а также отправляет некоторые переопределения для конкретных платформ. В частности, запрос:

  • устанавливает длительное время жизни для платформ Android и Web, а также низкий приоритет сообщений APNs (платформы Apple).
  • задает ключи, определяющие результат нажатия пользователем на уведомление на устройствах Android и Apple – click_action и category соответственно.
{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

Дополнительную информацию о ключах, доступных в блоках для конкретных платформ в теле сообщения, можно найти в справочном руководстве по HTTP v1. Подробнее о том, как создавать запросы на отправку, содержащие текст сообщения, с помощью FCM HTTP v1 API…

Уведомление с вариантами цвета и значка

В следующем примере запрос на отправку отправляет общий заголовок и содержимое уведомления на все платформы, но он также отправляет некоторые переопределения для конкретных платформ на устройства Android.

Для Android в запросе задается специальный значок и цвет, которые будут показываться на устройствах Android. Как указано в справочнике по AndroidNotification, цвет задается в формате #rrggbb, а изображение должно быть ресурсом значка, который можно отрисовать, локальным для приложения Android.

Вот пример того, как это выглядит на устройстве пользователя:

Простой рисунок двух устройств, на одном из которых показан пользовательский значок и цвет

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: '`$FooCorp` up 1.43% on the day',
    body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  android: {
    notification: {
      icon: 'stock_ticker_update',
      color: '#7e55c3'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

Message message = Message.builder()
    .setNotification(Notification.builder()
            .setTitle("$GOOG up 1.43% on the day")
            .setTitle("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
            .build())
    .setAndroidConfig(AndroidConfig.builder()
        .setTtl(3600 * 1000)
        .setNotification(AndroidNotification.builder()
            .setIcon("stock_ticker_update")
            .setColor("#f45342")
            .build())
        .build())
    .setApnsConfig(ApnsConfig.builder()
        .setAps(Aps.builder()
            .setBadge(42)
            .build())
        .build())
    .setTopic("industry-tech")
    .build();

Python

message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    android=messaging.AndroidConfig(
        ttl=datetime.timedelta(seconds=3600),
        priority='normal',
        notification=messaging.AndroidNotification(
            icon='stock_ticker_update',
            color='#f45342'
        ),
    ),
    apns=messaging.APNSConfig(
        payload=messaging.APNSPayload(
            aps=messaging.Aps(badge=42),
        ),
    ),
    topic='industry-tech',
)

Проложить маршрут

oneHour := time.Duration(1) * time.Hour
badge := 42
message := &messaging.Message{
	Notification: &messaging.Notification{
		Title: "$GOOG up 1.43% on the day",
		Body:  "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
	},
	Android: &messaging.AndroidConfig{
		TTL: &oneHour,
		Notification: &messaging.AndroidNotification{
			Icon:  "stock_ticker_update",
			Color: "#f45342",
		},
	},
	APNS: &messaging.APNSConfig{
		Payload: &messaging.APNSPayload{
			Aps: &messaging.Aps{
				Badge: &badge,
			},
		},
	},
	Topic: "industry-tech",
}

C#

var message = new Message
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Android = new AndroidConfig()
    {
        TimeToLive = TimeSpan.FromHours(1),
        Notification = new AndroidNotification()
        {
            Icon = "stock_ticker_update",
            Color = "#f45342",
        },
    },
    Apns = new ApnsConfig()
    {
        Aps = new Aps()
        {
            Badge = 42,
        },
    },
    Topic = "industry-tech",
};

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title": "`$FooCorp` up 1.43% on the day",
       "body": "FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
     },
     "android":{
       "notification":{
         "icon":"stock_ticker_update",
         "color":"#7e55c3"
       }
     }
   }
 }

Дополнительную информацию о ключах, доступных в блоках для конкретных платформ в теле сообщения, можно найти в справочнике по HTTP v1.

Уведомление с собственным изображением

Примечания

  • Размер изображений для уведомлений не должен превышать 1 МБ. Кроме того, на них распространяются ограничения, связанные со встроенной поддержкой изображений в Android.
  • Чтобы получать и обрабатывать изображения уведомлений в приложении Apple, необходимо добавить расширение Notification Service. Расширение службы уведомлений позволяет приложению обрабатывать изображение, доставленное в полезной нагрузке FCM, прежде чем показывать уведомление конечному пользователю. Пример кода можно найти в разделе Настройка расширения службы уведомлений.
  • Размер изображений, загружаемых с помощью Компоновщика уведомлений, не должен превышать 300 КБ.
  • На изображения, хранящиеся в Cloud Storage или передаваемые из него, распространяются стандартные ограничения квот.

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

  • Для Android задайте следующий параметр AndroidConfig:
    • notification.image, содержащий URL изображения.
  • Для iOS задайте следующие параметры ApnsConfig:
    • fcm_options.image, содержащий URL изображения. Apple требует, чтобы URL изображения содержал действительное расширение имени файла, позволяющее правильно определить тип ресурса.
    • headers({ "mutable-content": 1})

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

Простой рисунок изображения в уведомлении на экране

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Sparky says hello!'
  },
  android: {
    notification: {
      imageUrl: 'https://foo.bar.pizza-monster.png'
    }
  },
  apns: {
    payload: {
      aps: {
        'mutable-content': 1
      }
    },
    fcm_options: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  webpush: {
    headers: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"Sparky says hello!",
     },
     "android":{
       "notification":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "mutable-content":1
         }
       },
       "fcm_options": {
           "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "webpush":{
       "headers":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     }
   }
 }

Дополнительную информацию о ключах, доступных в блоках для конкретных платформ в теле сообщения, можно найти в справочнике по HTTP v1.

Уведомление со связанным действием по клику

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

Простой рисунок: пользователь нажимает на экран, чтобы открыть веб-страницу

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Breaking News....'
  },
  android: {
    notification: {
      clickAction: 'news_intent'
    }
  },
  apns: {
    payload: {
      aps: {
        'category': 'INVITE_CATEGORY'
      }
    }
  },
  webpush: {
    fcmOptions: {
      link: 'breakingnews.html'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1