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

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

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

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

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

از فیلدهای مشترک در موارد زیر استفاده کنید:

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

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

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

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

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

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

وقتی پیام‌هایی با گزینه‌های تحویل خاص ارسال می‌کنید، از فیلدهای مختص پلاتفرم برای تنظیم آن‌ها استفاده کنید. درصورت تمایل می‌توانید مقادیر مختلفی را برای هر پلاتفرم مشخص کنید. بااین‌حال، حتی زمانی که می‌خواهید مقدار اساساً یکسانی را در سراسر پلاتفرم‌ها تنظیم کنید، باید از فیلدهای مختص پلاتفرم استفاده کنید. دلیل این امر این است که هر پلاتفرم ممکن است مقدار را کمی متفاوت تفسیر کند—برای مثال، زمان ماندگاری در 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);
  });

جاوا

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