Dostosowywanie wiadomości na różnych platformach

Zestaw 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óre mają być interpretowane przez wszystkie instancje aplikacji otrzymujące wiadomość;
  • zestawy pól specyficzne dla platformy, takie jak AndroidConfig i WebpushConfig, interpretowane tylko przez instancje aplikacji działające na określonej platformie.

Bloki specyficzne dla platformy umożliwiają dostosowywanie wiadomości do różnych platform, aby zapewnić ich prawidłową obsługę po odebraniu. Backend FCM uwzględni wszystkie określone parametry i dostosuje wiadomość do każdej platformy.

Kiedy używać pól wspólnych

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

  • wysyłasz pola na dowolną platformę;
  • wysyłasz 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łać pola tylko na określone platformy;
  • wysyłać pola specyficzne dla platformy oprócz pól wspólnych.

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

Gdy wysyłasz wiadomości z określonymi opcjami dostarczania, użyj pól specyficznych dla platformy, aby je ustawić. W razie potrzeby możesz określić różne wartości dla każdej platformy. Jednak nawet jeśli chcesz ustawić zasadniczo tę samą wartość na wszystkich platformach, musisz użyć pól specyficznych dla platformy. Każda platforma może bowiem interpretować wartość nieco inaczej. Na przykład czas życia danych (TTL) jest ustawiany na Androidzie jako czas wygaśnięcia w sekundach, a na platformach Apple jako data wygaśnięcia.

Wiadomość z powiadomieniem i opcjami dostarczania specyficznymi dla platformy

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

  • ustawia długi czas życia danych (TTL) na platformach Android i internetowych, a priorytet wiadomości APNs (platformy Apple) na niski;
  • ustawia odpowiednie klucze, aby zdefiniować wynik kliknięcia powiadomienia przez użytkownika na Androidzie i Apple – odpowiednio 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 referencyjnej interfejsu HTTP v1 API, 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ść z powiadomieniem i opcjami koloru oraz ikony

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

W przypadku Androida żądanie ustawia specjalną ikonę i kolor, które mają być wyświetlane na urządzeniach z Androidem. Jak wspomnieliśmy w dokumentacji dla AndroidNotification, kolor jest określony w formacie #rrggbb, a obraz musi być zasobem ikony rysowalnej lokalnym dla 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")
        .setBody("$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 referencyjnej interfejsu HTTP v1 API, gdzie znajdziesz szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości.

Wiadomość z powiadomieniem i obrazem niestandardowym

Keep in mind:

  • Rozmiar obrazów w powiadomieniach jest ograniczony do 1 MB, a poza tym obowiązują ograniczenia wynikające z wbudowanej obsługi obrazów w Androidzie.
  • Aby móc odbierać i obsługiwać obrazy w powiadomieniach w aplikacji na 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 przydziału.

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 op0}cje ApnsConfig:
    • fcm_options.image zawierający adres URL obrazu. Apple wymaga, aby adres URL obrazu zawierał prawidłowe rozszerzenie pliku, które pozwoli prawidłowo zidentyfikować typ zasobu.
    • headers({ "mutable-content": 1})

To żądanie wysyłania wysyła wspólny tytuł powiadomienia na wszystkie platformy, ale 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 referencyjnej interfejsu HTTP v1 API, gdzie znajdziesz szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości.

Wiadomość z powiadomieniem i powiązanym działaniem po kliknięciu

To żądanie wysyłania wysyła wspólny tytuł powiadomienia na wszystkie platformy, ale 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