سفارشی‌سازی پیام در پلاتفرم‌های مختلف

Firebase Admin SDK و FCM v1 HTTP API به درخواست‌های پیام شما اجازه می‌دهد تا همه فیلدهای دردسترس در شیء message را تنظیم کنند. این شامل موارد زیر است:

  • مجموعه مشترکی از فیلدها که توسط همه نمونه‌های برنامه که پیام را دریافت می‌کنند تفسیر می‌شود.
  • مجموعه فیلدهای مختص پلاتفرم، مثل AndroidConfig و WebpushConfig، که فقط توسط نمونه‌های برنامه درحال اجرا در پلاتفرم مشخص‌شده تفسیر می‌شوند.

بلوک‌های مختص پلاتفرم به شما انعطاف‌پذیری می‌دهند تا پیام‌ها را برای پلاتفرم‌های مختلف سفارشی‌سازی کنید و مطمئن شوید که هنگام دریافت به‌درستی مدیریت می‌شوند. بخش پشتی FCM همه پارامترهای مشخص‌شده را درنظر می‌گیرد و پیام را برای هر پلاتفرم سفارشی‌سازی می‌کند.

زمان استفاده از فیلدهای رایج

از فیلدهای رایج استفاده کنید وقتی:

  • ارسال فیلدها به هر پلاتفرمی
  • ارسال پیام به موضوعات

همه نمونه‌های برنامه، صرف‌نظر از پلاتفرم، می‌توانند فیلدهای مشترک زیر را تفسیر کنند:

چه زمانی از فیلدهای مختص پلاتفرم استفاده کنیم

وقتی می‌خواهید کارهای زیر را انجام دهید، از فیلدهای مختص پلاتفرم استفاده کنید:

  • فیلدها را فقط به پلاتفرم‌های خاصی ارسال کنید
  • فیلدهای مختص پلاتفرم را علاوه‌بر فیلدهای مشترک ارسال کنید

هرگاه خواستید مقادیر را فقط به پلاتفرم‌های خاصی ارسال کنید، از فیلدهای مختص پلاتفرم استفاده کنید. برای مثال، برای ارسال اعلان فقط به پلاتفرم‌های Apple و Web و نه به Android، باید از دو مجموعه فیلد جداگانه استفاده کنید، یکی برای Apple و یکی برای Web.

وقتی پیام‌هایی با گزینه‌های تحویل خاص ارسال می‌کنید، از فیلدهای مختص پلاتفرم برای تنظیم آن‌ها استفاده کنید. درصورت تمایل می‌توانید مقادیر متفاوتی را برای هر پلاتفرم مشخص کنید. بااین‌حال، حتی وقتی می‌خواهید اساساً مقدار یکسانی را در پلاتفرم‌ها تنظیم کنید، باید از فیلدهای مختص پلاتفرم استفاده کنید. دلیلش این است که هر پلاتفرم ممکن است مقدار را کمی متفاوت تفسیر کند—برای مثال، زمان بقا در Android به‌عنوان زمان انقضا برحسب ثانیه تنظیم می‌شود، درحالی‌که در Apple به‌عنوان تاریخ انقضا تنظیم می‌شود.

پیام اعلان با گزینه‌های تحویل مختص پلاتفرم

درخواست ارسال HTTP v1 API زیر عنوان و محتوای اعلان مشترکی را به همه پلاتفرم‌ها ارسال می‌کند، اما برخی‌از لغوهای خاص پلاتفرم را نیز ارسال می‌کند. به‌طور دقیق، درخواست:

  • زمان طولانی‌ای را برای پلاتفرم‌های Android و وب تنظیم می‌کند، درحالی‌که اولویت پیام APN (پلاتفرم‌های 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);
  });

جاوا

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();

پایتون

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

سی شارپ

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 مراجعه کنید تا جزئیات بیشتری درباره کلیدهای موجود در بلوک‌های مختص پلاتفرم در بدنه پیام دریافت کنید.

پیام اعلان با تصویر سفارشی

به‌خاطر داشته باشید:

  • اندازه تصاویر برای اعلان‌ها به ۱ مگابایت محدود است و درغیراین‌صورت توسط پشتیبانی تصویر داخلی Android محدود می‌شوند.
  • برای اینکه بتوانید تصاویر اعلان را در برنامه Apple دریافت و مدیریت کنید، باید افزونه سرویس اعلان را اضافه کنید. افزونه سرویس اعلان به برنامه شما اجازه می‌دهد تصویر ارائه‌شده در بار FCM را قبل‌از نمایش اعلان به کاربر نهایی مدیریت کند، برای نمونه کد به راه‌اندازی افزونه سرویس اعلان مراجعه کنید.
  • اندازه تصاویر بارگذاری‌شده بااستفاده از «سازنده اعلان‌ها» به ۳۰۰ کیلوبایت محدود است.
  • تصاویر ذخیره‌شده یا ارائه‌شده از Cloud Storage مشمول محدودیت‌های سهمیه استاندارد هستند.

در درخواست ارسال اعلان، گزینه‌های زیر را تنظیم کنید تا کارخواه گیرنده بتواند تصویر ارائه‌شده در بار را مدیریت کند:

  • برای Android، گزینه AndroidConfig زیر را تنظیم کنید:
    • ‫notification.image حاوی نشانی وب تصویر
  • برای iOS، گزینه‌های ApnsConfig زیر را تنظیم کنید:
    • fcm_options.image حاوی نشانی وب تصویر. Apple برای شناسایی صحیح نوع منبع، لازم می‌داند که نشانی وب تصویر حاوی پسوند فایل معتبر باشد.
    • 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