با API Notifications شروع کنید

در این لبه کد، از ویژگی‌های اساسی Notifications API برای موارد زیر استفاده خواهید کرد:

  • درخواست مجوز برای ارسال اعلان‌ها
  • ارسال نوتیفیکیشن
  • گزینه های اعلان را آزمایش کنید

پشتیبانی مرورگر

  • کروم: 20.
  • لبه: 14.
  • فایرفاکس: 22.
  • سافاری: 7.

منبع

اعلان‌ها به‌طور خودکار از برنامه Glitch تعبیه‌شده مسدود می‌شوند، بنابراین نمی‌توانید برنامه را در این صفحه پیش‌نمایش کنید. در عوض، در اینجا چه باید کرد:

  1. روی Remix to Edit کلیک کنید تا پروژه قابل ویرایش باشد.
  2. برای پیش نمایش سایت، View App را فشار دهید. سپس تمام صفحه را فشار دهید تمام صفحه .

اشکال باید در یک برگه کروم جدید باز شود:

تصویری که برنامه زنده ریمیکس شده را در یک برگه جدید نشان می دهد

همانطور که از طریق این لبه کد کار می کنید، تغییراتی در کد موجود در Glitch تعبیه شده در این صفحه ایجاد کنید. برای مشاهده تغییرات، برگه جدید را با برنامه زنده خود بازخوانی کنید.

با برنامه شروع و کد آن آشنا شوید

با بررسی برنامه زنده در برگه جدید Chrome شروع کنید:

  1. «Control+Shift+J» (یا «Command+Option+J» در Mac) را فشار دهید تا DevTools باز شود. روی تب Console کلیک کنید.

    شما باید پیام زیر را در کنسول مشاهده کنید:

    Notification permission is default
    

    اگر معنی آن را نمی دانید، نگران نباشید. همه چیز به زودی آشکار خواهد شد!

  2. روی دکمه‌های برنامه زنده کلیک کنید: درخواست مجوز برای ارسال اعلان‌ها و ارسال اعلان .

    کنسول پیام های "TODO" را از چند تابع چاپ می کند: requestPermission و sendNotification . اینها توابعی هستند که در این کد لبه پیاده سازی خواهید کرد.

حالا بیایید به کد برنامه نمونه در Glitch تعبیه شده در این صفحه نگاه کنیم. public/index.js را باز کنید و به بخش‌های مهم کد موجود نگاهی بیندازید:

  • تابع showPermission از Notifications API برای دریافت وضعیت مجوز فعلی سایت و ورود آن به کنسول استفاده می کند:

    // Print current permission state to console;
    // update onscreen message.
    function showPermission() {
      let permission = Notification.permission;
      console.log('Notification permission is ' + permission);
      let p = document.getElementById('permission');
      p.textContent = 'Notification permission is ' + permission;
    }
    

    قبل از درخواست مجوز، وضعیت مجوز default است. در وضعیت مجوز default ، یک سایت باید قبل از ارسال اعلان‌ها درخواست کند و به آن مجوز داده شود.

  • تابع requestPermission یک خرد است:

    // Use the Notification API to request permission to send notifications.
    function requestPermission() {
      console.log('TODO: Implement requestPermission()');
    }
    

    در مرحله بعد این تابع را پیاده سازی خواهید کرد.

  • تابع sendNotification یک خرد است:

    // Use the Notification constructor to create and send a new Notification.
    function sendNotification() {
      console.log('TODO: Implement sendNotification()');
    }
    

    شما این تابع را پس از اجرای requestPermission پیاده سازی خواهید کرد.

  • شنونده رویداد window.onload تابع showPermission را هنگام بارگیری صفحه فراخوانی می کند و وضعیت مجوز فعلی را در کنسول و صفحه نمایش می دهد:

    window.onload = () => { showPermission(); };
    

درخواست مجوز برای ارسال اعلان‌ها

در این مرحله، قابلیتی را برای درخواست اجازه کاربر برای ارسال اعلان‌ها اضافه می‌کنید.

شما از روش Notification.requestPermission() برای راه اندازی پنجره ای استفاده خواهید کرد که از کاربر می خواهد اعلان های سایت شما را مجاز یا مسدود کند.

  1. کد زیر را جایگزین تابع requestPermission در public/index.js کنید:

    // Use the Notification API to request permission to send notifications.
    function requestPermission() {
      Notification.requestPermission()
        .then((permission) => {
          console.log('Promise resolved: ' + permission);
          showPermission();
        })
        .catch((error) => {
          console.log('Promise was rejected');
          console.log(error);
        });
    }
    
  2. برگه Chrome را که در آن برنامه زنده خود را مشاهده می کنید، دوباره بارگیری کنید.

  3. در رابط برنامه زنده، روی درخواست مجوز برای ارسال اعلان‌ها کلیک کنید. یک پنجره بازشو ظاهر می شود.

کاربر می تواند یکی از سه پاسخ را به پنجره بازشوی مجوز بدهد.

پاسخ کاربر وضعیت مجوز اعلان
کاربر Allow را انتخاب می کند granted
کاربر Block را انتخاب می کند denied
کاربر بدون انتخاب گزینه پنجره بازشو را رد می کند default

اگر کاربر روی Allow کلیک کند:

  • Notification.permission روی granted تنظیم شده است.

  • سایت قادر به نمایش اعلان ها خواهد بود.

  • تماس‌های بعدی با Notification.requestPermission بدون پنجره بازشو granted می‌شود.

اگر کاربر روی Block کلیک کند:

  • Notification.permission روی denied شده است.

  • سایت نمی تواند اعلان ها را به کاربر نمایش دهد.

  • تماس‌های بعدی به Notification.requestPermission بدون پنجره بازشو denied می‌شوند.

اگر کاربر پنجره بازشو را رد کند:

  • Notification.permission default باقی می ماند.

  • سایت نمی تواند اعلان ها را به کاربر نمایش دهد.

  • تماس‌های بعدی به Notification.requestPermission پنجره‌های بازشو بیشتری ایجاد می‌کند.

    با این حال، اگر کاربر همچنان به رد کردن پنجره‌های بازشو ادامه دهد، ممکن است مرورگر سایت را مسدود کند و Notification.permission را روی denied . نه پنجره های درخواست مجوز و نه اعلان ها را نمی توان به کاربر نمایش داد.

    در زمان نگارش این مقاله، رفتار مرورگر در پاسخ به پنجره‌های بازشو مجوز اعلان‌های رد شده همچنان در معرض تغییر است. بهترین راه برای رسیدگی به این موضوع این است که همیشه در پاسخ به برخی از تعاملاتی که کاربر آغاز کرده است، مجوز اعلان درخواست کنید تا آنها منتظر آن باشند و بدانند چه خبر است.

یک اعلان ارسال کنید

در این مرحله یک اعلان برای کاربر ارسال می کنید.

شما از سازنده Notification برای ایجاد یک اعلان جدید و تلاش برای نمایش آن استفاده خواهید کرد. اگر وضعیت مجوز granted شود، اعلان شما نمایش داده می شود.

  1. کد زیر را جایگزین تابع sendNotification در index.js کنید:

    // Use the Notification constructor to create and send a new Notification.
    function sendNotification() {
      let title = 'Test';
      let options = {
        body: 'Test body',
        // Other options can go here
      };
      console.log('Creating new notification');
      let notification = new Notification(title, options);
    }
    

    سازنده Notification دو پارامتر را می گیرد: title و options . options یک شی با ویژگی های نمایش دهنده تنظیمات بصری و داده هایی است که می توانید در یک اعلان قرار دهید. برای اطلاعات بیشتر به مستندات MDN در مورد پارامترهای اعلان مراجعه کنید.

  2. برگه Chrome را که در آن برنامه زنده خود را مشاهده می کنید بازخوانی کنید و روی دکمه ارسال اعلان کلیک کنید. یک اعلان با متن Test body باید ظاهر شود.

وقتی اعلان‌ها را بدون اجازه ارسال می‌کنید چه اتفاقی می‌افتد؟

در این مرحله، چند خط کد اضافه می‌کنید که به شما امکان می‌دهد ببینید وقتی می‌خواهید یک اعلان را بدون اجازه کاربر نمایش دهید، چه اتفاقی می‌افتد.

  • در public/index.js ، در انتهای تابع sendNotification ، کنترل کننده رویداد onerror اعلان جدید را تعریف کنید:
// Use the Notification constructor to create and send a new Notification.
function sendNotification() {
  let title = 'Test';
  let options = {
    body: 'Test body',
    // Other options can go here
  };
  console.log('Creating new notification');
  let notification = new Notification(title, options);
  notification.onerror = (event) => {
    console.log('Could not send notification');
    console.log(event);
  };
}

برای مشاهده خطای مجوز اعلان:

  1. روی نماد قفل در کنار نوار URL Chrome کلیک کنید و تنظیمات مجوز اعلان سایت را به حالت پیش فرض بازنشانی کنید.

  2. روی درخواست مجوز برای ارسال اعلان‌ها کلیک کنید و این بار Block را از پنجره بازشو انتخاب کنید.

  3. روی ارسال اعلان کلیک کنید و ببینید چه اتفاقی می افتد. متن خطا ( Could not send notification ) و شی رویداد در کنسول ثبت می‌شوند.

در صورت تمایل، دوباره مجوزهای اعلان سایت را بازنشانی کنید. می توانید چندین بار درخواست مجوز و رد کردن پنجره بازشو را امتحان کنید تا ببینید چه اتفاقی می افتد.

گزینه های اعلان را آزمایش کنید

اکنون اصول اولیه نحوه درخواست مجوز و ارسال اعلان ها را پوشش داده اید. همچنین دیده‌اید که پاسخ‌های کاربران چه تأثیری بر توانایی برنامه شما برای نمایش اعلان‌ها دارد.

اکنون می‌توانید هنگام ایجاد اعلان، گزینه‌های دیداری و داده‌ای زیادی را آزمایش کنید. مجموعه کامل گزینه های موجود در زیر آمده است. (برای اطلاعات بیشتر در مورد این گزینه ها به مستندات اعلان در MDN مراجعه کنید.)

توجه داشته باشید که مرورگرها و دستگاه‌ها این گزینه‌ها را متفاوت اجرا می‌کنند، بنابراین ارزش دارد اعلان‌های خود را در پلتفرم‌های مختلف آزمایش کنید تا ببینید چگونه به نظر می‌رسند.

let options = {
  dir: 'auto',              // Text direction
  lang: 'en-US',            // A language tag
  badge: '/orange-cat.png', // Display when insufficient room
  body: 'Hello World',      // Body text
  tag: 'mytag',             // Tag for categorization
  icon: '/line-cat.png',    // To display in the notification
  image: '/orange-cat.png', // To display in the notification
  data: {                   // Arbitrary data; any data type
    cheese: 'I like cheese',
    pizza: 'Excellent cheese delivery mechanism',
    arbitrary: {
      faveNumber: 42,
      myBool: true
    }},
  vibrate: [200, 100, 200], // Vibration pattern for hardware
  renotify: false,          // Notify if replaced? Default false
  requireInteraction: false,// Active until click? Default false
  /*
    actions:   // Array of NotificationActions
               // Only usable with a service worker
    [{
      action: 'shop',
      title: 'Shop!',
      icon: '/bags.png'
    },],
  */
}

برای ایده‌های بیشتر ، پیتر بورلو را ببینید!

اگر گیر کردید، کد تکمیل‌شده برای این لبه کد اینه: glitch.com/edit/#!/codelab-notifications-get-started-completed

برای کاوش بیشتر ، به آزمایشگاه کد بعدی در این مجموعه نگاهی بیندازید.