اعلان وب webpush
فرستادن اعلان به مرورگرها از سرور، با کلیدهای VAPID و رمزنگاری استاندارد.
واردسازی اعلان وب
نام آرگومانها شناسهی خود کد است و معادل فارسی ندارد؛ گونهها، کلیدواژهها و نام بستهها با معادل فارسی نوشته میشوند.
اعلان وب پیامی است که سرور حتی وقتی سایت باز نیست به مرورگر کاربر میفرستد: پیام تازهی گفتگو، ارسال شدن سفارش یا خبر فوری. این بسته سمت سرور است. کلیدهای VAPID را که سرور شما را معرفی میکنند میسازد، هر پیام را طبق RFC 8291 (aes128gcm) برای یک مرورگر رمز میکند تا سرویس اعلانِ میانه محتوایش را نبیند، درخواست را امضا میکند و آن را با اچ تی تی پی میفرستد. سمت صفحه جاوااسکریپت معمولی است: یک service worker و pushManager.subscribe.
روند کار:
- یک بار با
ساخت کلیدهاجفت کلید بسازید و نگهش دارید؛ بعدها باکلیدها ازبارش کنید. - صفحه با کلید عمومی مشترک میشود و JSON اشتراک را برایتان میفرستد؛ آن را به شکل یک
اشتراککنار کاربر ذخیره کنید. - با
ارسالپیام بفرستید و وقتی نتیجهgoneگفت، اشتراک را پاک کنید.
چیزهایی که بیشتر غافلگیر میکنند:
- کلید تازه همهی اشتراکها را از کار میاندازد. هر اشتراک به کلید عمومیای گره خورده که با آن ساخته شده است.
ttlبرابر ۰ با پیشفرض ۲۸ روزه جایگزین میشود، پس «همین حالا برسان یا دور بینداز» را نمیشود گفت؛ به جایش مقدار کوتاهی مثل ۶۰ بدهید.- اندازهی پیام بررسی نمیشود. متن بیشتر از ۳۹۹۳ بایت باز هم رمز و فرستاده میشود و سرویس اعلان، معمولاً با ۴۱۳، آن را رد میکند.
ارسالهر قدر سرویس اعلان طول بکشد منتظر میماند و مهلت ندارد، پس فرستادن پشت سر هم برای هزاران کاربر ممکن است کند باشد.کلیدها ازفقط خالی نبودن دو کلید را میسنجد.
کلیدهای VAPID را یک بار بسازید
جفت کلید VAPID سرور شما را به سرویسهای اعلان معرفی میکند و هر اشتراک مرورگر به کلید عمومی آن بسته است. اگر با هر بار اجرا کلید تازه بسازید، همهی اشتراکهای قبلی از کار میافتند. پس کلیدها را یک بار بسازید، جای امنی نگه دارید و از آن پس با کلیدها از بارشان کنید. برنامهی زیر آنها را در یک فایل نگه میدارد؛ سرور واقعی معمولاً آنها را از پیکربندی یا متغیرهای محیطی میخواند.
واردسازی اعلان وب
واردسازی سیستم عامل
واردسازی رشته
تابع کلیدهای ماندگار(مسیر: رشته): اعلان وب.کلیدها:
اگر سیستم عامل.وجود دارد(مسیر):
خطها := رشته.تفکیک کردن(سیستم عامل.خواندن پرونده(مسیر)، "\n")
اگر خطها.طول() >= ۲:
برگشت اعلان وب.کلیدها از(خطها.بگیر(۰)، خطها.بگیر(۱))
پایان
پایان
تازه := اعلان وب.ساخت کلیدها()
سیستم عامل.نوشتن پرونده(مسیر، تازه.کلید عمومی + "\n" + تازه.کلید خصوصی + "\n")
برگشت تازه
پایان
تابع ریشه:
مسیر := "vapid-keys.txt"
نخست := کلیدهای ماندگار(مسیر)
دوم := کلیدهای ماندگار(مسیر)
سرچاپ "کلیدها معتبر:"، نخست.معتبر، دوم.معتبر
سرچاپ "همان کلیدها در اجرای دوم:"، نخست.کلید عمومی برابر دوم.کلید عمومی
سرچاپ "طول کلید عمومی:"، نخست.کلید عمومی.طول()
سرچاپ "نقطهی فشرده نشده (با B آغاز میشود):"، رشته.شروع با(نخست.کلید عمومی، "B")
سیستم عامل.حذف(مسیر)
پایانکلید عمومی همان متن ۸۷ نویسهای است که صفحه به عنوان applicationServerKey به pushManager.subscribe میدهد. کلید خصوصی هرگز از سرور بیرون نمیرود.
خواندن اشتراکی که مرورگر میفرستد
پس از اینکه کاربر اجازهی اعلان داد، pushManager.subscribe() در صفحه یک اشتراک برمیگرداند. شکل toJSON() آن یک endpoint و دو کلید p256dh و auth دارد. این JSON را به سرور بفرستید، با کدگذاری/جیسون در یک اشتراک بخوانید و کنار کاربر ذخیره کنید. رمزنگاری با آرگومان آخرش میگوید کلیدها قابل استفادهاند یا نه؛ این راه سادهای است برای رد کردن اشتراک خراب پیش از ذخیره.
واردسازی اعلان وب
واردسازی کدگذاری.جیسون
واردسازی رشته
تابع از مرورگر(متن: رشته): اعلان وب.اشتراک:
برگشت اعلان وب.اشتراک {
نقطه پایانی = جیسون.دریافت(متن، "endpoint")،
کلید مرورگر = جیسون.دریافت مسیر(متن، "keys.p256dh")،
راز احراز هویت = جیسون.دریافت مسیر(متن، "keys.auth")
}
پایان
تابع ریشه:
رسیده := `{"endpoint":"https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91b","expirationTime":null,"keys":{"p256dh":"BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4","auth":"BTBZMqHH6r4Tts7J_aSIgg"}}`
اشتراک := از مرورگر(رسیده)
سرچاپ "نشانی:"، اشتراک.نقطه پایانی
سرچاپ "سرویس گوگل:"، رشته.شروع با(اشتراک.نقطه پایانی، "https://fcm.googleapis.com/")
سرچاپ "طول p256dh:"، اشتراک.کلید مرورگر.طول()، "طول auth:"، اشتراک.راز احراز هویت.طول()
ناپایا موفق := نادرست
بدنه := اعلان وب.رمزنگاری(اشتراک، "{\"title\":\"خوش آمدید\"}"، موفق)
سرچاپ "کلیدها قابل استفاده:"، موفق، "بدنهی رمز شده آماده:"، بدنه.طول() > ۰
خراب := از مرورگر(`{"endpoint":"https://push.example.net/1","keys":{"p256dh":"abc","auth":"xyz"}}`)
_ := اعلان وب.رمزنگاری(خراب، "سلام"، موفق)
سرچاپ "کلیدهای خراب قابل استفاده:"، موفق
پایانبار پیام را کوچک نگه دارید
هر پیام پس از رمزگذاری حداکثر ۴۰۹۶ بایت جا دارد که ۳۹۹۳ بایتش برای متن شماست. بیشتر سرویسها پیام کوچک را هم زودتر میرسانند. یک عنوان، یک متن کوتاه و یک پیوند بفرستید و بگذارید صفحه هر چیز بزرگتر را وقتی کاربر اعلان را باز کرد خودش بگیرد. برنامه نشان میدهد اندازه چطور بزرگ میشود: بدنهی رمز شده یک سرآیند ثابت و لایهی پرکننده میگیرد و base64url آن را باز هم یک سوم بلندتر میکند. متن فارسی هم در UTF-8 برای هر حرف دو بایت میگیرد، برای همین پیام کوچک اینجا از نسخهی انگلیسیاش بلندتر است.
واردسازی اعلان وب
واردسازی کدگذاری.جیسون
تابع بار(عنوان: رشته، متن: رشته، نشانی: رشته): رشته:
ناپایا عضوها := وکتور {} برگردان وکتور<رشته>
عضوها.بیفزا(جیسون.عضو("title"، عنوان))
عضوها.بیفزا(جیسون.عضو("body"، متن))
عضوها.بیفزا(جیسون.عضو("url"، نشانی))
برگشت جیسون.شیء(عضوها)
پایان
تابع ریشه:
اشتراک := اعلان وب.اشتراک {
نقطه پایانی = "https://push.example.net/x"،
کلید مرورگر = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4"،
راز احراز هویت = "BTBZMqHH6r4Tts7J_aSIgg"
}
کوچک := بار("پاسخ تازه"، "سارا به پرسش شما پاسخ داد"، "/q/1042")
سرچاپ کوچک
ناپایا موفق := نادرست
هر اندازه در [کوچک.طول()، ۱۰۰۰، ۳۰۰۰، ۳۹۹۳]:
ناپایا متن := ""
تا متن.طول() < اندازه:
متن += "x"
پایان
مهر شده := اعلان وب.رمزنگاری(اشتراک، متن، موفق)
سرچاپ "متن ساده"، اندازه، "بایت، پس از رمز و base64url"، مهر شده.طول()
پایان
پایانفرستادن به کاربران زیاد و پاکسازی
برای خبر دادن به همه، روی اشتراکهای ذخیره شده بچرخید و برای هر کدام ارسال را صدا بزنید. به نتیجه نگاه کنید: ok یعنی سرویس اعلان پیام را پذیرفت، gone (HTTP ۴۰۴ یا ۴۱۰) یعنی کاربر اشتراک را لغو کرده یا مرورگر آن را کنار گذاشته، پس پاکش کنید؛ هر چیز دیگری را بعداً دوباره امتحان کنید. ttl میگوید سرویس تا کی پیام را برای دستگاه خاموش نگه دارد، urgency به گوشی اجازه میدهد برای پیام کماهمیت باتری را نگه دارد، و پیامی با همان topic جای پیام قدیمیتری را که هنوز در صف است میگیرد.
واردسازی اعلان وب
تابع ریشه:
کلیدها := اعلان وب.کلیدها از("BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE"، "Nhh4m4Va4yhL-53i302044iqeAeMtnOEYlIT2KWRJmg")
اگر وارونه کلیدها.معتبر:
سرچاپ "کلیدهای VAPID خراباند"
برگشت ۱
پایان
ناپایا اشتراکها := وکتور {} برگردان وکتور<اعلان وب.اشتراک>
اشتراکها.بیفزا(اعلان وب.اشتراک { نقطه پایانی = "https://fcm.googleapis.com/fcm/send/abc"، کلید مرورگر = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4"، راز احراز هویت = "BTBZMqHH6r4Tts7J_aSIgg" })
اشتراکها.بیفزا(اعلان وب.اشتراک { نقطه پایانی = "https://updates.push.services.mozilla.com/wpush/v2/def"، کلید مرورگر = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4"، راز احراز هویت = "BTBZMqHH6r4Tts7J_aSIgg" })
ناپایا گزینه := اعلان وب.گزینههای جدید("mailto:ops@example.com")
گزینه.مدت نگهداری = ۳۶۰۰
گزینه.فوریت = "high"
گزینه.موضوع = "deploy"
ناپایا ماندنی := وکتور {} برگردان وکتور<اعلان وب.اشتراک>
ناپایا فرستاده := ۰
هر اشتراک در اشتراکها:
نتیجه := اعلان وب.ارسال(کلیدها، اشتراک، `{"title":"انتشار تمام شد","body":"نسخهی ۲.۴ در دسترس است"}`، گزینه)
اگر نتیجه.موفق:
فرستاده++
ماندنی.بیفزا(اشتراک)
وگرنه نتیجه.منقضی:
سرچاپ "حذف"، اشتراک.نقطه پایانی
وگرنه:
سرچاپ "تلاش دوباره بعدا"، اشتراک.نقطه پایانی، نتیجه.وضعیت، نتیجه.خطا
ماندنی.بیفزا(اشتراک)
پایان
پایان
سرچاپ "فرستاده شد"، فرستاده، "از"، اشتراکها.طول()، "و ماندنی"، ماندنی.طول()
برگشت ۰
پایاناین برنامه به اشتراکهای واقعی از مرورگر و دسترسی به شبکه نیاز دارد، پس اینجا فقط بررسی میشود. برای امتحان، نشانیهای نمونه را با اشتراکهایی که از صفحهی خودتان گرفتهاید عوض کنید.
گونهها
کلیدها Keys
ساختار کلیدها| نام | انگلیسی | گونه | توضیح |
|---|---|---|---|
| کلید عمومی | public_key | رشته = "" | کلید عمومی به شکل بیس۶۴ نشانیامن؛ همین را در جاوااسکریپت صفحه به applicationServerKey بدهید. |
| کلید خصوصی | private_key | رشته = "" | کلید خصوصی؛ آن را پنهان نگه دارید. |
| معتبر | ok | منطقی = نادرست | کلیدها معتبرند. |
واردسازی اعلان وب
واردسازی رشته
تابع ریشه:
تازه := اعلان وب.ساخت کلیدها()
سرچاپ تازه.معتبر، تازه.کلید عمومی.طول()، تازه.کلید خصوصی.طول()
ک := اعلان وب.کلیدها از("BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE"، "Nhh4m4Va4yhL-53i302044iqeAeMtnOEYlIT2KWRJmg")
سرچاپ ک.معتبر، اعلان وب.کلیدها از(""، "").معتبر
س := اعلان وب.سرصفحه واپید در زمان(ک، "https://fcm.googleapis.com"، "mailto:ali@example.com"، ۱۷۰۰۰۰۰۰۰۰)
سرچاپ س
ا := اعلان وب.سرصفحه واپید(ک، "https://fcm.googleapis.com"، "mailto:ali@example.com")
سرچاپ رشته.شروع با(ا، "vapid t=")، رشته.شامل است(ا، ", k=" + ک.کلید عمومی)
ناپایا گ := اعلان وب.گزینههای جدید("mailto:ali@example.com")
سرچاپ گ.موضوع تماس، گ.مدت نگهداری == اعلان وب.ماندگاری پیشفرض، گ.مدت نگهداری / ۸۶۴۰۰
گ.فوریت = "high"
گ.موضوع = "news"
گ.مدت نگهداری = ۳۶۰۰
سرچاپ گ.فوریت، گ.موضوع، گ.مدت نگهداری
پایاناشتراک Subscription
ساختار اشتراکpushManager.subscribe میسازد و به سرور شما میفرستد.| نام | انگلیسی | گونه | توضیح |
|---|---|---|---|
| نقطه پایانی | endpoint | رشته = "" | نشانی سرویس اعلان مرورگر. |
| کلید مرورگر | p256dh | رشته = "" | کلید عمومی مرورگر از بخش keys اشتراک. |
| راز احراز هویت | auth | رشته = "" | راز احراز هویت از همان بخش. |
واردسازی اعلان وب
تابع ریشه:
ا := اعلان وب.اشتراک {
نقطه پایانی = "https://push.example.net/x"،
کلید مرورگر = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4"،
راز احراز هویت = "BTBZMqHH6r4Tts7J_aSIgg"
}
ناپایا سالم := نادرست
بدنه := اعلان وب.رمزنگاری سفارشی(ا، "When I grow up, I want to be a watermelon"، "yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw"، "DGv6ra1nlYgDCS1FRnbzlw"، سالم)
سرچاپ سالم
سرچاپ بدنه
یک := اعلان وب.رمزنگاری(ا، "سلام"، سالم)
دو := اعلان وب.رمزنگاری(ا، "سلام"، سالم)
سرچاپ سالم، یک != دو، یک.طول() == دو.طول()
پایانگزینهها Options
ساختار گزینهها| نام | انگلیسی | گونه | توضیح |
|---|---|---|---|
| موضوع تماس | subject | رشته = "" | نشانی تماس شما، به شکل mailto: یا نشانی وب؛ سرویسها آن را لازم دارند. |
| مدت نگهداری | ttl | صحیح = 2419200 | چند ثانیه سرویس پیام را برای مرورگر خاموش نگه دارد. صفر یا کمتر پیشفرض ۲۸ روزه را میفرستد. |
| فوریت | urgency | رشته = "" | فوریت: very-low، low، normal یا high؛ خالی یعنی سرآیندی فرستاده نمیشود و سرویس آن را عادی میگیرد. مقدار بررسی نمیشود. |
| موضوع | topic | رشته = "" | موضوع؛ پیام تازه با همان موضوع جای پیام تحویلنشدهی قبلی را میگیرد. |
نمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam
نتیجه Result
ساختار نتیجه| نام | انگلیسی | گونه | توضیح |
|---|---|---|---|
| موفق | ok | منطقی = نادرست | سرویس پیام را پذیرفت. |
| وضعیت | status | صحیح = 0 | کد وضعیت HTTP سرویس. |
| منقضی | gone | منطقی = نادرست | اشتراک دیگر معتبر نیست (۴۰۴ یا ۴۱۰)؛ آن را از پایگاه داده پاک کنید. |
| خطا | error | رشته = "" | دلیل شکست: خطای شبکه، یا بدنهی پاسخ سرویس اگر کوتاه باشد. |
واردسازی اعلان وب
تابع ریشه:
ک := اعلان وب.کلیدها از("BLmOwafYGSjiuCX_1RSCO_n0YmacxYMDqitMydKE4A1Wp2qmUuMXg2IM_hzcrmZLun4jEu_lKfVdtnAp0LMK4NE"، "Nhh4m4Va4yhL-53i302044iqeAeMtnOEYlIT2KWRJmg")
ا := اعلان وب.اشتراک {
نقطه پایانی = "https://fcm.googleapis.com/fcm/send/abc"،
کلید مرورگر = "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4"،
راز احراز هویت = "BTBZMqHH6r4Tts7J_aSIgg"
}
گ := اعلان وب.گزینههای جدید("mailto:ali@example.com")
ن := اعلان وب.ارسال(ک، ا، `{"title":"سلام","body":"پیام تازه دارید"}`، گ)
اگر ن.موفق:
سرچاپ "فرستاده شد"، ن.وضعیت
وگرنه ن.منقضی:
سرچاپ "اشتراک منقضی شده؛ آن را پاک کنید"
وگرنه:
سرچاپ "خطا:"، ن.وضعیت، ن.خطا
پایان
پایانپایاها و متغیرها
ماندگاری پیشفرض DEFAULT_TTL
پایا ماندگاری پیشفرض: صحیح۳۲ = 2419200نمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam
تابعها
ساخت کلیدها GenerateKeys
تابع ساخت کلیدها(): کلیدهانمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam
سرصفحه واپید در زمان VapidHeaderAt
تابع سرصفحه واپید در زمان(keys: کلیدها، audience: رشته، subject: رشته، epoch_seconds: صحیح۶۴): رشتهAuthorization برای سرویسی که نشانیاش داده شده، با زمان دادهشده بر حسب ثانیهی یونیکس. امضا قطعی است، پس با ورودی یکسان خروجی یکسان است.نمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam
سرصفحه واپید VapidHeader
تابع سرصفحه واپید(keys: کلیدها، audience: رشته، subject: رشته): رشتهنمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam
رمزنگاری سفارشی EncryptWith
تابع رمزنگاری سفارشی(sub: اشتراک، payload: رشته، as_private: رشته، salt: رشته، ok &: منطقی): رشتهرمزنگاری را به کار ببرید.نمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Encrypt.salam
رمزنگاری Encrypt
تابع رمزنگاری(sub: اشتراک، payload: رشته، ok &: منطقی): رشتهنمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Encrypt.salam
ارسال Send
تابع ارسال(keys: کلیدها، sub: اشتراک، payload: رشته، opts: گزینهها): نتیجهنمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Send.salam
گزینههای جدید NewOptions
تابع گزینههای جدید(subject: رشته): گزینههانمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam
کلیدها از KeysFrom
تابع کلیدها از(public_key: رشته، private_key: رشته): کلیدهاok نادرست است. خود کلیدها تا نخستین ارسال بررسی نمیشوند.نمونهی این مورد همراه با موارد بالاتر آمده است: webpush-Keys.salam