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

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

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

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