התאמה אישית של הודעה בפלטפורמות שונות

‫Firebase Admin SDK ו-FCM v1 HTTP API מאפשרים לבקשות ההודעות להגדיר את כל השדות שזמינים באובייקט message. זה כולל:

  • קבוצה משותפת של שדות שכל מופעי האפליקציה שמקבלים את ההודעה מפרשים אותם.
  • קבוצות של שדות ספציפיים לפלטפורמה, כמו AndroidConfig ו-WebpushConfig, שרק מופעי אפליקציה שפועלים בפלטפורמה שצוינה יכולים לפרש.

בלוקים ספציפיים לפלטפורמה מאפשרים לכם להתאים אישית הודעות לפלטפורמות שונות, כדי לוודא שהן יטופלו בצורה נכונה כשהן יתקבלו. ה-backend של FCM יביא בחשבון את כל הפרמטרים שצוינו ויתאים אישית את ההודעה לכל פלטפורמה.

מתי כדאי להשתמש בשדות נפוצים

כדאי להשתמש בשדות נפוצים כשאתם:

  • שליחת שדות לכל פלטפורמה
  • שליחת הודעות לנושאים

כל המופעים של האפליקציה, בלי קשר לפלטפורמה, יכולים לפרש את השדות הנפוצים הבאים:

מתי כדאי להשתמש בשדות ספציפיים לפלטפורמה

כדאי להשתמש בשדות ספציפיים לפלטפורמה כשרוצים:

  • שליחת שדות רק לפלטפורמות מסוימות
  • שליחת שדות ספציפיים לפלטפורמה בנוסף לשדות הנפוצים

אם אתם רוצים לשלוח ערכים רק לפלטפורמות מסוימות, השתמשו בשדות ספציפיים לפלטפורמה. לדוגמה, כדי לשלוח התראה רק לפלטפורמות של אפל ושל האינטרנט, אבל לא ל-Android, צריך להשתמש בשתי קבוצות נפרדות של שדות, אחת לאפל ואחת לאינטרנט.

כששולחים הודעות עם אפשרויות מסירה ספציפיות, צריך להשתמש בשדות ספציפיים לפלטפורמה כדי להגדיר אותן. אם רוצים, אפשר לציין ערכים שונים לכל פלטפורמה. עם זאת, גם אם אתם רוצים להגדיר ערך זהה בכל הפלטפורמות, אתם צריכים להשתמש בשדות ספציפיים לפלטפורמה. הסיבה לכך היא שכל פלטפורמה עשויה לפרש את הערך בצורה קצת שונה. לדוגמה, זמן החיים מוגדר ב-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',
)

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

למידע נוסף, עיינו בדף חומר עזר בנושא HTTP v1 כדי לקבל פרטים נוספים על המפתחות שזמינים בבלוקים ספציפיים לפלטפורמה בגוף ההודעה.

הודעה עם תמונה מותאמת אישית

חשוב לזכור:

  • גודל התמונות בהתראות מוגבל ל-1MB, והן כפופות למגבלות של התמיכה בתמונות המובנית ב-Android.
  • כדי לקבל ולטפל בתמונות של התראות באפליקציה של אפל, צריך להוסיף תוסף של שירות התראות. תוסף שירות ההתראות מאפשר לאפליקציה לטפל בתמונה שנשלחה במטען הייעודי (payload) של FCM לפני שההתראה מוצגת למשתמש הקצה. דוגמת קוד זמינה במאמר הגדרת תוסף שירות ההתראות.
  • גודל התמונות שמעלים באמצעות הכלי לניסוח מסרים מוגבל ל-300KB.
  • תמונות שמאוחסנות ב-Cloud Storage או מוצגות ממנו כפופות למגבלות המכסות הרגילות.

בבקשה לשליחת ההתראה, מגדירים את האפשרויות הבאות כדי לאפשר ללקוח המקבל לטפל בתמונה שנשלחה במטען הייעודי (payload):

  • ב-Android, מגדירים את האפשרות הבאה של AndroidConfig:
    • notification.image שמכיל את כתובת ה-URL של התמונה
  • ב-iOS, מגדירים את האפשרויות הבאות של ApnsConfig:
    • fcm_options.image שמכיל את כתובת ה-URL של התמונה. אפל דורשת שכתובת ה-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