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

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

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

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

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

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

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

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

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

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

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

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

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

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

يرسل طلب الإرسال التالي في الإصدار الأول من واجهة برمجة التطبيقات HTTP عنوان إشعار ومحتوى شائعَين إلى جميع الأنظمة الأساسية، ولكنه يرسل أيضًا بعض عمليات الإلغاء الخاصة بالنظام الأساسي. وعلى وجه التحديد، يجب أن يستوفي الطلب ما يلي:

  • يضبط مدة صلاحية طويلة لمنصّتَي 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 للحصول على مزيد من التفاصيل حول المفاتيح المتاحة في المجموعات الخاصة بالنظام الأساسي في نص الرسالة. لمزيد من المعلومات حول إنشاء طلبات إرسال تحتوي على نص الرسالة، يُرجى الاطّلاع على إرسال رسالة باستخدام الإصدار 1 من واجهة برمجة تطبيقات HTTP لمراسلة Firebase السحابية.

رسالة إشعار مع خيارات الألوان والرموز

في المثال التالي، يرسل طلب الإرسال عنوان إشعار ومحتوى مشتركَين إلى جميع المنصات، ولكنه يرسل أيضًا بعض عمليات الإلغاء الخاصة بمنصة معيّنة إلى أجهزة 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',
)

متابعة

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 للحصول على مزيد من التفاصيل حول المفاتيح المتاحة في الوحدات الخاصة بالنظام الأساسي في نص الرسالة.

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

تنبيه:

  • يجب ألا يتجاوز حجم صور الإشعارات 1 ميغابايت، وإلا ستخضع لقيود دعم الصور المضمّنة في Android.
  • لتتمكّن من تلقّي صور الإشعارات ومعالجتها في تطبيق Apple، عليك إضافة إضافة خدمة الإشعارات. تتيح إضافة خدمة الإشعارات لتطبيقك معالجة الصورة التي يتم تسليمها في حمولة FCM قبل عرض الإشعار للمستخدم النهائي، راجِع إعداد إضافة خدمة الإشعارات للحصول على عينة تعليمات برمجية.
  • يقتصر حجم الصور التي يتم تحميلها باستخدام "منشئ الإشعارات" على 300 كيلوبايت.
  • تخضع الصور المخزّنة أو المعروضة من Cloud Storage لحدود الحصة العادية.

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

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