Dostosowywanie wiadomości na różnych platformach

Firebase Admin SDK i interfejs FCM v1 HTTP API umożliwiają ustawianie w żądaniach wiadomości wszystkich pól dostępnych w obiekcie message. Obejmuje to:

  • wspólny zestaw pól, który ma być interpretowany przez wszystkie instancje aplikacji otrzymujące wiadomość.
  • zestawy pól specyficzne dla platformy, np. AndroidConfig i WebpushConfig, interpretowane tylko przez instancje aplikacji działające na określonej platformie.

Blokowanie na poziomie platformy daje Ci możliwość dostosowywania wiadomości do różnych platform, aby mieć pewność, że po otrzymaniu będą one prawidłowo obsługiwane. Backend FCM uwzględni wszystkie określone parametry i dostosuje wiadomość do każdej platformy.

Kiedy używać wspólnych pól

Używaj wspólnych pól, gdy:

  • Wysyłanie pól na dowolną platformę
  • Wysyłanie wiadomości do tematów

Wszystkie instancje aplikacji, niezależnie od platformy, mogą interpretować te wspólne pola:

Kiedy używać pól specyficznych dla platformy

Używaj pól specyficznych dla platformy, gdy chcesz:

  • Wysyłanie pól tylko na określone platformy
  • Wysyłanie pól specyficznych dla platformy oprócz pól wspólnych

Jeśli chcesz wysyłać wartości tylko na określone platformy, używaj pól specyficznych dla platformy. Jeśli na przykład chcesz wysłać powiadomienie tylko na platformy Apple i internetowe, ale nie na Androida, musisz użyć 2 osobnych zestawów pól – jednego dla Apple i jednego dla platform internetowych.

Gdy wysyłasz wiadomości z określonymi opcjami dostawy, używaj pól specyficznych dla platformy, aby je ustawić. W razie potrzeby możesz określić różne wartości dla poszczególnych platform. Nawet jeśli chcesz ustawić zasadniczo tę samą wartość na różnych platformach, musisz użyć pól specyficznych dla danej platformy. Dzieje się tak, ponieważ każda platforma może interpretować tę wartość nieco inaczej. Na przykład na Androidzie czas życia danych (TTL) jest ustawiany jako czas wygaśnięcia w sekundach, a na urządzeniach Apple jako data wygaśnięcia.

Wiadomość z powiadomieniem z opcjami dostawy na poszczególnych platformach

To żądanie wysyłania interfejsu HTTP v1 API wysyła wspólny tytuł powiadomienia i treść na wszystkie platformy, ale także niektóre zastąpienia specyficzne dla platformy. W szczególności prośba:

  • ustawia długi czas życia danych (TTL) na platformach Android i w internecie, a priorytet wiadomości APNs (platformy Apple) na niski.
  • ustawia odpowiednie klucze, aby zdefiniować wynik kliknięcia powiadomienia przez użytkownika na urządzeniu z Androidem i Apple – click_action i 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"
       }
     }
   }
 }

Więcej informacji znajdziesz na stronie Dokumentacja HTTP v1, gdzie znajdziesz szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości. Więcej informacji o tworzeniu żądań wysyłania zawierających treść wiadomości znajdziesz w artykule Wysyłanie wiadomości za pomocą interfejsu FCM HTTP v1 API.

Wiadomość powiadomienia z opcjami kolorów i ikon

W poniższym przykładzie żądanie wysyłania przesyła wspólny tytuł i treść powiadomienia na wszystkie platformy, ale także niektóre zastąpienia specyficzne dla platformy na urządzenia z Androidem.

W przypadku Androida żądanie ustawia specjalną ikonę i kolor do wyświetlania na urządzeniach z Androidem. Jak wspomniano w dokumentacji AndroidNotification, kolor jest określany w formacie #rrggbb, a obraz musi być obiektem rysowalnym w zasobach lokalnych aplikacji na Androida.

Oto przykład efektu wizualnego na urządzeniu użytkownika:

Prosty rysunek dwóch urządzeń, z których jedno wyświetla niestandardową ikonę i kolor

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',
)

Go

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"
       }
     }
   }
 }

Więcej informacji znajdziesz na stronie HTTP v1 reference (w języku angielskim), gdzie znajdziesz szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości.

Wiadomość z powiadomieniem zawierająca obraz niestandardowy

Keep in mind:

  • Obrazy w powiadomieniach mogą mieć maksymalnie 1 MB. W innych przypadkach obowiązują ograniczenia wynikające z wbudowanej w Androida obsługi obrazów.
  • Aby móc otrzymywać i obsługiwać obrazy w powiadomieniach w aplikacji na urządzenia Apple, musisz dodać rozszerzenie usługi powiadomień. Rozszerzenie usługi powiadomień umożliwia aplikacji obsługę obrazu dostarczonego w ładunku FCM przed wyświetleniem powiadomienia użytkownikowi. Przykładowy kod znajdziesz w artykule Konfigurowanie rozszerzenia usługi powiadomień.
  • Rozmiar obrazów przesyłanych za pomocą narzędzia do tworzenia powiadomień jest ograniczony do 300 KB.
  • Obrazy przechowywane lub udostępniane z Cloud Storage podlegają standardowym limitom.

W żądaniu wysłania powiadomienia ustaw te opcje, aby umożliwić klientowi odbierającemu obsługę obrazu dostarczonego w ładunku:

  • W przypadku Androida ustaw tę opcję AndroidConfig:
    • notification.image zawierający adres URL obrazu.
  • W przypadku iOS ustaw te opcje ApnsConfig:
    • fcm_options.image zawierający adres URL obrazu. Firma Apple wymaga, aby adres URL obrazu zawierał prawidłowe rozszerzenie pliku, które umożliwia prawidłowe rozpoznanie typu zasobu.
    • headers({ "mutable-content": 1})

Poniższa prośba o wysłanie powiadomienia zawiera wspólny tytuł powiadomienia na wszystkich platformach, ale wysyła też obraz. Oto przykład efektu wizualnego na urządzeniu użytkownika:

Prosty rysunek obrazu w powiadomieniu displayowym

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"
       }
     }
   }
 }

Więcej informacji znajdziesz na stronie HTTP v1 reference (w języku angielskim), gdzie znajdziesz szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości.

Komunikat powiadomienia z powiązanym działaniem kliknięcia

Poniższe żądanie wysyłania zawiera wspólny tytuł powiadomienia na wszystkie platformy, ale wysyła też działanie, które aplikacja ma wykonać w odpowiedzi na interakcję użytkownika z powiadomieniem. Oto przykład efektu wizualnego na urządzeniu użytkownika:

Prosty rysunek przedstawiający użytkownika, który otwiera stronę internetową

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