تخصيص رسالة على جميع المنصات

يتيح لك كلّ من Firebase Admin SDK وFCM v1 HTTP API لطلبات الرسائل ضبط جميع الحقول المتاحة في message عنصر. ويشمل ذلك:

  • مجموعة شائعة من الحقول التي يجب أن تفسّرها جميع مثيلات التطبيقات التي تتلقّى الرسالة
  • مجموعات من الحقول الخاصة بالمنصات، مثل AndroidConfig وWebpushConfig، التي تفسّرها فقط مثيلات التطبيقات التي تعمل على المنصة المحدّدة

تمنحك البلوكات الخاصة بالمنصات مرونة تخصيص الرسائل لمنصات مختلفة لضمان معالجتها بشكل صحيح عند تلقّيها. سيأخذ نظام FCM الخلفي في الاعتبار جميع المعلمات المحدّدة ويخصّص الرسالة لكل منصة.

حالات استخدام الحقول الشائعة

يمكنك استخدام الحقول الشائعة في الحالات التالية:

  • إرسال حقول إلى أي منصة
  • إرسال رسائل إلى المواضيع

يمكن لجميع مثيلات التطبيقات، بغض النظر عن المنصة، تفسير الحقول الشائعة التالية:

حالات استخدام الحقول الخاصة بالمنصات

يمكنك استخدام الحقول الخاصة بالمنصات في الحالات التالية:

  • إرسال حقول إلى منصات معيّنة فقط
  • إرسال حقول خاصة بالمنصات بالإضافة إلى الحقول الشائعة

عندما تريد إرسال قيم إلى منصات معيّنة فقط، استخدِم الحقول الخاصة بالمنصات. على سبيل المثال، لإرسال إشعار إلى منصتَي Apple والويب فقط وليس إلى Android، عليك استخدام مجموعتَين منفصلتَين من الحقول، إحداهما لمنصة Apple والأخرى لمنصة الويب.

عند إرسال رسائل تتضمّن خيارات تسليم محدّدة، استخدِم الحقول الخاصة بالمنصات لضبطها. يمكنك تحديد قيم مختلفة لكل منصة إذا أردت ذلك. ومع ذلك، حتى إذا أردت ضبط القيمة نفسها بشكل أساسي على جميع المنصات، عليك استخدام الحقول الخاصة بالمنصات. ويرجع ذلك إلى أنّ كل منصة قد تفسّر القيمة بشكل مختلف قليلاً، على سبيل المثال، يتم ضبط مدة بقاء الرسالة على 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")
        .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"
       }
     }
   }
 }

لمزيد من المعلومات، يمكنك الاطّلاع على صفحة مرجع HTTP v1 لمزيد من التفاصيل حول المفاتيح المتاحة في البلوكات الخاصة بالمنصات في نص الرسالة.

رسالة إشعار تتضمّن صورة مخصّصة

Keep in mind:

في طلب إرسال الإشعار، اضبط الخيارات التالية لتمكين العميل المتلقّي من معالجة الصورة التي يتم تسليمها في الحمولة:

  • بالنسبة إلى 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