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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • устанавливает длительное время жизни для платформ Android и веб-платформ, а также низкий приоритет сообщений 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