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

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 reference. Подробнее о том, как создавать запросы на отправку, содержащие тело сообщения…

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

В следующем примере запрос на отправку содержит стандартный заголовок и контент уведомления для всех платформ, а также некоторые переопределения для устройств 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 версии 1. В ней вы найдете подробные сведения о ключах, доступных в блоках для разных платформ в теле сообщения.

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

Примечания

  • Размер изображений для уведомлений ограничен 1 МБ. В остальном они должны соответствовать требованиям Android к изображениям.
  • Чтобы получать и обрабатывать изображения в уведомлениях в приложении для устройств Apple, необходимо добавить расширение службы уведомлений. Расширение службы уведомлений позволяет приложению обрабатывать изображение, полученное в полезной нагрузке 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 версии 1. В ней вы найдете подробные сведения о ключах, доступных в блоках для разных платформ в теле сообщения.

Уведомление с действием при нажатии

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

Простое изображение нажатия пользователя, открывающего веб-страницу

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