path: root/files/ru/conflicting/web/api/push_api/index.html

---
title: Использование Push API
slug: conflicting/Web/API/Push_API
translation_of: Web/API/Push_API
translation_of_original: Web/API/Push_API/Using_the_Push_API
original_slug: Web/API/Push_API/Using_the_Push_API
---
<p class="summary"><span class="seoSummary">W3C <a href="/en-US/docs/Web/API/Push_API">Push API</a> предоставляет некоторую захватывающую новую функциональность для разработчиков для использования в web-приложениях: эта статья предлагает вводную информацию о том, как настроить Push-уведомления и управлять ими, с помощью простого демо.</span></p>

<p>Возможность посылать сообщения или уведомления от сервера клиенту в любое время — независимо от того, активно приложение или нет — было прерогативой нативных приложений некоторое время, и наконец пришло в Web! Поддерживается большинства возможностей Push сейчас возможна в браузерах Firefox 43+ и Chrome 42+ на настольных компьютерах, мобильные платформы, возможно, скоро присоединятся. {{domxref("PushMessageData")}} на данный момент экспериментально поддерживаются только в Firefox Nightly (44+), и реализация может меняться.</p>

<div class="note">
<p><strong>Примечание</strong>: Ранние версии Firefox OS использовали проприетарную версию этого API вызывая <a href="/en-US/docs/Web/API/Simple_Push_API">Simple Push</a>. Считается устаревшим по стандартам Push API.</p>
</div>

<h2 id="Демо_основы_простого_сервера_чат-приложения">Демо: основы простого сервера чат-приложения</h2>

<p>Демо, которые мы создали, представляет начальное описание простого чат-приложения. Оно представляет собой форму, в которую вводятся данные, и кнопку для подписки на push-сообщения . Как только кнопка будет нажата, вы подпишитесь на push-сообщения, ваши данные будут записаны на сервере, а отправленное push-сообщение сообщит всем текущим подписчикам, что кто-то подписался.</p>

<p>На данном этапе, имя нового подписчика появится в списке подписчиков, вместе с текстовым полем и кнопкой рассылки, чтобы позволить подписчику отправить сообщение.</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/11823/push-api-demo.png" style="border: 1px solid black; display: block; height: 406px; margin: 0px auto; width: 705px;"></p>

<p>Чтобы запустить демо, следуйте инструкциям на странице <a href="https://github.com/chrisdavidmills/push-api-demo">push-api-demo README</a>. Заметьте, что серверная компонента все ещё нуждается в небольшой доработке для запуска в Chrome и в общем запускается более разумным путём. Но аспекты Push все ещё могут быть полностью понятны; мы углубимся в это после того, как просмотрим технологии в процессе.</p>

<h2 id="Обзор_технологии">Обзор технологии</h2>

<p>Эта секция предоставляет описание того, какие технологии участвуют в примере.</p>

<p>Web Push-сообщения это часть семейства технологий <a href="/en-US/docs/Web/API/Service_Worker_API">сервис воркеров</a>; в первую очередь, для получения push-сообщений сервис воркер должен быть активирован на странице. Сервис воркер получает push-сообщения, и затем вы сами решаете, как уведомить об этом страницу. Вы можете:</p>

<ul>
 <li>Отправить <a href="/en-US/docs/Web/API/Notifications_API">Web-уведомление</a>, которое вызовет всплытие системного уведомления. Для этого необходимо подтверждение разрешения на отправку push-сообщений.</li>
 <li>Отправить сообщение обратно главной странице через {{domxref("MessageChannel")}}.</li>
</ul>

<p>Обычно необходима комбинация этих двух решений; демо внизу включает пример обоих.</p>

<div class="note">
<p><strong>Примечание</strong>: вам необходим некоторый код, запущенный на сервере, для управления конечной точкой/шифрованием данных и отправки запросов push-сообщений. В нашем демо мы собрали на скорую руку сервер, используя <a href="https://nodejs.org/">NodeJS</a>.</p>
</div>

<p>Сервис воркер так же должен подписаться на сервис push-сообщений. Каждой сессии предоставляется собственная уникальная конечная точка, когда она подписывается на сервис push-сообщений. Эта конечная точка получается из свойства  ({{domxref("PushSubscription.endpoint")}}) объекта подписчика. Она может быть отправлена серверу и использоваться для пересылки сообщений активному сервис воркеру сессии. Каждый браузер имеет свой собственный сервер push-сообщений для  управления отправкой push-сообщений.</p>

<h3 id="Шифрование">Шифрование</h3>

<div class="note">
<p><strong>Примечание</strong>: Для интерактивного краткого обзора, попробуйте JR Conlin's <a href="https://jrconlin.github.io/WebPushDataTestPage/">Web Push Data Encryption Test Page</a>.</p>
</div>

<p>Для отправки данных с помощью push-сообщений необходимо шифрование. Для этого необходим публичный ключ, созданный с использованием метода  {{domxref("PushSubscription.getKey()")}}, который основывается на некотором комплексе механизмов шифрования, которые выполняются на стороне сервера; читайте <a href="https://tools.ietf.org/html/draft-ietf-webpush-encryption-01">Message Encryption for Web Push</a>. Со временем появятся библиотеки для управления генерацией ключей и шифрованием/дешифрованием push-сообщений; для этого демо мы используем Marco Castelluccio's NodeJS <a href="https://github.com/marco-c/web-push">web-push library</a>.</p>

<div class="note">
<p><strong>Примечание</strong>: Есть так же другая библиотека для управления шифрованием с помощью Node и Python, смотри <a href="https://github.com/martinthomson/encrypted-content-encoding">encrypted-content-encoding</a>.</p>
</div>

<h3 id="Обобщение_рабочего_процесса_Push">Обобщение рабочего процесса Push</h3>

<p>Общие сведения ниже это то, что необходимо для реализации push-сообщений. Вы можете найти больше информации о некоторых частях демо в последующих частях.</p>

<ol>
 <li>Запрос на разрешение web-уведомлений или что-то другое, что вы используете и для чего необходимо разрешение.</li>
 <li>Регистрация сервис воркера для контроля над страницей с помощью вызова {{domxref("ServiceWorkerContainer.register()")}}.</li>
 <li>Подписка на сервис push-уведомлений с помощью {{domxref("PushManager.subscribe()")}}.</li>
 <li>Запрашивание конечной точки, соответствующей подписчику, и генерация публичного ключа клиента ({{domxref("PushSubscription.endpoint")}} и {{domxref("PushSubscription.getKey()")}}. Заметьте, что <code>getKey()</code> на данный момент экспериментальная технологий и доступна только в Firefox.)</li>
 <li>Отправка данных на сервер, чтобы тот мог присылать push-сообщения, когда необходимо. Это демо использует {{domxref("XMLHttpRequest")}}, но вы можете использовать <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a>.</li>
 <li>Если вы используете <a href="/en-US/docs/Web/API/Channel_Messaging_API">Channel Messaging API</a> для связи с сервис воркером, установите новый канал связи ({{domxref("MessageChannel.MessageChannel()")}}) и отправьте <code>port2</code> сервис воркеру с помощью вызова {{domxref("Worker.postMessage()")}} для того, чтобы открыть канал связи. Вы так же должны настроить обработчик ответов на сообщения, которые будут отправляться обратно с сервис воркера.</li>
 <li>На стороне сервера сохраните конечную точку и все остальные необходимые данные, чтобы они были доступны, когда будет необходимо отправить push-сообщение добавленному подписчику (мы используем простой текстовый файл, но вы можете использовать базу данных или все что угодно на ваш вкус). В приложении на продакшене убедитесь, что скрываете эти данные, так что злоумышленники не смогут украсть конечную точку и разослать спам подписчикам в push-сообщениях.</li>
 <li>Для отправки push-сообщений необходимо отослать HTTP <code>POST</code> конечному URL. Запрос должен включать <code>TTL</code> заголовок, который ограничивает время пребывания сообщения в очереди, если пользователь не в сети. Для добавления полезной информации в запросе, необходимо зашифровать её (что включает публичный ключ клиента). В нашем примере мы используем <a href="https://github.com/marco-c/web-push">web-push</a> модуль, который управляет всей тяжёлой работой.</li>
 <li>Поверх в сервис воркере настройте обработчик событий <code>push</code> для ответов на полученные push-сообщения.
  <ol>
   <li>Если вы хотите отвечать отправкой сообщения канала обратно основному контексту (смотри шаг 6), необходимо сначала получить ссылку на <code>port2,</code> который был отправлен контексту сервис воркера ({{domxref("MessagePort")}}). Это доступно в объекте  {{domxref("MessageEvent")}}, передаваемого обработчику <code>onmessage </code>({{domxref("ServiceWorkerGlobalScope.onmessage")}}). Конкретнее, он находится в свойстве <code>ports</code>, индекс 0. Когда это сделано, вы можете отправить сообщение обратно <code>port1</code>, используя {{domxref("MessagePort.postMessage()")}}.</li>
   <li>Если вы хотите ответить запуском системного уведомления, вы можете сделать это, вызвав {{domxref("ServiceWorkerRegistration.showNotification()")}}. Заметьте, что в нашем коде мы вызываем его внутри метода {{domxref("ExtendableEvent.waitUntil()")}} — это растягивает время жизни события, пока уведомление не будет запущено, так что мы можем убедиться, что все, что мы хотели, чтобы произошло, действительно произошло.<span id="cke_bm_307E" class="hidden"> </span></li>
  </ol>
 </li>
</ol>

<h2 id="Сборка_демо">Сборка демо</h2>

<p>Давайте пройдёмся по коду для демо, чтобы понять, как все работает.</p>

<h3 id="HTML_и_CSS">HTML и CSS</h3>

<p>Нет ничего примечательного в HTML и CSS демо; HTML содержит простую форму для ввода данных для входа в чат, кнопку для подписки на push-уведомления и двух списков, в которых перечислены подписчики и сообщения чата. После подписки появляются дополнительные средства для того, чтобы пользователь мог ввести сообщение в чат.</p>

<p>CSS был оставлен очень минимальным, чтобы не отвлекать от объяснения того, как функционируют Push API.</p>

<h3 id="Основной_файл_JavaScript">Основной файл JavaScript</h3>

<p> JavaScript очевидно намного более существенный. Давайте взглянем на основной файл JavaScript.</p>

<h4 id="Переменные_и_начальные_настройки">Переменные и начальные настройки</h4>

<p>Для начала определим некоторые переменные, которые будем использовать в нашем приложении:</p>

<pre class="brush: js">var isPushEnabled = false;
var useNotifications = false;

var subBtn = document.querySelector('.subscribe');
var sendBtn;
var sendInput;

var controlsBlock = document.querySelector('.controls');
var subscribersList = document.querySelector('.subscribers ul');
var messagesList = document.querySelector('.messages ul');

var nameForm = document.querySelector('#form');
var nameInput = document.querySelector('#name-input');
nameForm.onsubmit = function(e) {
  e.preventDefault()
};
nameInput.value = 'Bob';</pre>

<p>Сначала нам необходимо создать две булевы переменные, для того чтобы отслеживать подписку на push-сообщения и подтверждение разрешения на рассылку уведомлений.</p>

<p>Далее, мы перехватываем ссылку на {{htmlelement("button")}} подписки/отписки и задаём переменные для сохранения ссылок на наши кнопку отправки сообщения/ввода (который создастся только после успешной подписки).<br>
 <br>
 Следующие переменные перехватывают ссылки на три основные {{htmlelement("div")}} элемента, так что мы можем включить в них элементы (к примеру, когда появится кнопка <em>Отправки Сообщения Чата</em> или сообщение появится с писке <em>Сообщений</em>).</p>

<p>Finally we grab references to our name selection form and {{htmlelement("input")}} element, give the input a default value, and use <code><a href="/en-US/docs/Web/API/Event/preventDefault">preventDefault()</a></code> to stop the form submitting when the form is submitted by pressing return.</p>

<p>Next, we request permission to send web notifications, using {{domxref("Notification.requestPermission","requestPermission()")}}:</p>

<pre class="brush: js">Notification.requestPermission();</pre>

<p>Now we run a section of code when <code><a href="/en-US/docs/Web/API/GlobalEventHandlers/onload">onload</a></code> is fired, to start up the process of inialising the app when it is first loaded. First of all we add a click event listener to the subscribe/unsubscribe button that runs our <code>unsubscribe()</code> function if we are already subscribed (<code>isPushEnabled</code> is <code>true</code>), and <code>subscribe()</code> otherwise:</p>

<pre class="brush: js">window.addEventListener('load', function() {
  subBtn.addEventListener('click', function() {
    if (isPushEnabled) {
      unsubscribe();
    } else {
      subscribe();
    }
  });</pre>

<p>Next we check to see if service workers are supported. If so, we register a service worker using {{domxref("ServiceWorkerContainer.register()")}}, and run our <code>initialiseState()</code> function. If not, we deliver an error message to the console.</p>

<pre class="brush: js">  // Check that service workers are supported, if so, progressively
  // enhance and add push messaging support, otherwise continue without it.
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('sw.js').then(function(reg) {
      if(reg.installing) {
        console.log('Service worker installing');
      } else if(reg.waiting) {
        console.log('Service worker installed');
      } else if(reg.active) {
        console.log('Service worker active');
      }

      initialiseState(reg);
    });
  } else {
    console.log('Service workers aren\'t supported in this browser.');
  }
});
</pre>

<p>The next thing in the source code is the <code>initialiseState()</code> function — for the full commented code, look at the <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/main.js"><code>initialiseState()</code> source on Github</a> (we are not repeating it here for brevity's sake.)</p>

<p><code>initialiseState()</code> first checks whether notifications are supported on service workers, then sets the <code>useNotifications</code> variable to <code>true</code> if so. Next, it checks whether said notifications are permitted by the user, and if push messages are supported, and reacts accordingly to each.</p>

<p>Finally, it uses {{domxref("ServiceWorkerContainer.ready()")}} to wait until the service worker is active and ready to start doing things. Once its promise resolves, we retrieve our subscription to push messaging using the {{domxref("ServiceWorkerRegistration.pushManager")}} property, which returns a {{domxref("PushManager")}} object that we then call {{domxref("PushManager.getSubscription()")}} on. Once this second inner promise resolves, we enable the subscribe/unsubscribe button (<code>subBtn.disabled = false;</code>), and check that we have a subscription object to work with.</p>

<p>If we do, then we are already subscribed. This is possible when the app is not open in the browser; the service worker can still be active in the background. If we're subscribed, we update the UI to show that we are subscribed by updating the button label, then we set <code>isPushEnabled</code> to <code>true</code>, grab the subscription endpoint from {{domxref("PushSubscription.endpoint")}}, generate a public key using {{domxref("PushSubscription.getKey()")}}, and run our <code>updateStatus()</code> function, which as you'll see later communicates with the server.</p>

<p>As an added bonus, we set up a new {{domxref("MessageChannel")}} using the {{domxref("MessageChannel.MessageChannel()")}} constructor, grab a reference to the active service worker using {{domxref("ServiceworkerRegistration.active")}}, then set up a channel betweeen the main browser context and the service worker context using {{domxref("Worker.postMessage()")}}. The browser context receives messages on {{domxref("MessageChannel.port1")}}; whenever that happens, we run the <code>handleChannelMessage()</code> function to decide what to do with that data (see the {{anch("Handling channel messages sent from the service worker")}} section).</p>

<h4 id="Subscribing_and_unsubscribing">Subscribing and unsubscribing</h4>

<p>Let's now turn our attention to the <code>subscribe()</code> and <code>unsubscribe()</code> functions used to subscribe/unsubscribe to the push notification service.</p>

<p>In the case of subscription, we again check that our service worker is active and ready by calling {{domxref("ServiceWorkerContainer.ready()")}}. When the promise resolves, we subscribe to the service using {{domxref("PushManager.subscribe()")}}. If the subscription is successful, we get a {{domxref("PushSubscription")}} object, extract the subscription endpoint from this and generate a public key (again, {{domxref("PushSubscription.endpoint")}} and {{domxref("PushSubscription.getKey()")}}), and pass them to our <code>updateStatus()</code> function along with the update type (<code>subscribe</code>) to send the necessary details to the server.</p>

<p>We also make the necessary updates to the app state (set <code>isPushEnabled</code> to <code>true</code>) and UI (enable the subscribe/unsubscribe button and set its label text to show that the next time it is pressed it will unsubscribe.)</p>

<p>The <code>unsubscribe()</code> function is pretty similar in structure, but it basically does the opposite; the most notable difference is that it gets the current subscription using {{domxref("PushManager.getSubscription()")}}, and when that promise resolves it unsubscribes using {{domxref("PushSubscription.unsubscribe()")}}.</p>

<p>Appropriate error handling is also provided in both functions.  </p>

<p>We only show the <code>subscribe()</code> code below, for brevity; see the full <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/main.js">subscribe/unsubscribe code on Github</a>.</p>

<pre class="brush: js">function subscribe() {
  // Disable the button so it can't be changed while
  // we process the permission request

  subBtn.disabled = true;

  navigator.serviceWorker.ready.then(function(reg) {
    reg.pushManager.subscribe({userVisibleOnly: true})
      .then(function(subscription) {
        // The subscription was successful
        isPushEnabled = true;
        subBtn.textContent = 'Unsubscribe from Push Messaging';
        subBtn.disabled = false;

        // Update status to subscribe current user on server, and to let
        // other users know this user has subscribed
        var endpoint = subscription.endpoint;
        var key = subscription.getKey('p256dh');
        updateStatus(endpoint,key,'subscribe');
      })
      .catch(function(e) {
        if (Notification.permission === 'denied') {
          // The user denied the notification permission which
          // means we failed to subscribe and the user will need
          // to manually change the notification permission to
          // subscribe to push messages
          console.log('Permission for Notifications was denied');

        } else {
          // A problem occurred with the subscription, this can
          // often be down to an issue or lack of the gcm_sender_id
          // and / or gcm_user_visible_only
          console.log('Unable to subscribe to push.', e);
          subBtn.disabled = false;
          subBtn.textContent = 'Subscribe to Push Messaging';
        }
      });
  });
}</pre>

<h4 id="Updating_the_status_in_the_app_and_server">Updating the status in the app and server</h4>

<p>The next function in our main JavaScript is <code>updateStatus()</code>, which updates the UI for sending chat messages when subscribing/unsubscribing and sends a request to update this information on the server.</p>

<p>The function does one of three different things, depending on the value of the <code>statusType</code> parameter passed into it:</p>

<ul>
 <li><code>subscribe</code>: The button and text input for sending chat messages are created and inserted into the UI, and an object is sent to the server via XHR containing the status type (<code>subscribe</code>), username of the subscriber, subscription endpoint, and client public key.</li>
 <li><code>unsubscribe</code>: This basically works in the opposite way to subscribe — the chat UI elements are removed, and an object is sent to the server to tell it that the user has unsubscribed.</li>
 <li><code>init</code>: This is run when the app is first loaded/initialised — it creates the chat UI elements, and sends an object to the server to tell it that which user has reinitialised (reloaded.)</li>
</ul>

<p>Again, we have not included the entire function listing for brevity. Examine the <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/main.js">full <code>updateStatus()</code> code on Github</a>.</p>

<h4 id="Handling_channel_messages_sent_from_the_service_worker">Handling channel messages sent from the service worker</h4>

<p>As mentioned earlier, when a <a href="/en-US/docs/Web/API/Channel_Messaging_API">channel message</a> is received from the service worker, our <code>handleChannelMessage()</code> function is called to handle it. This is done by our handler for the {{event("message")}} event, {{domxref("channel.port1.onmessage")}}:</p>

<pre class="brush: js">channel.port1.onmessage = function(e) {
  handleChannelMessage(e.data);
}</pre>

<p>This occurs when the <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/sw.js#L8">service worker sends a channel message over</a>.</p>

<p>The <code>handleChannelMessage()</code> function looks like this:</p>

<pre class="brush: js">function handleChannelMessage(data) {
  if(data.action === 'subscribe' || data.action === 'init') {
    var listItem = document.createElement('li');
    listItem.textContent = data.name;
    subscribersList.appendChild(listItem);
  } else if(data.action === 'unsubscribe') {
    for(i = 0; i &lt; subscribersList.children.length; i++) {
      if(subscribersList.children[i].textContent === data.name) {
        subscribersList.children[i].parentNode.removeChild(subscribersList.children[i]);
      }
    }
    nameInput.disabled = false;
  } else if(data.action === 'chatMsg') {
    var listItem = document.createElement('li');
    listItem.textContent = data.name + ": " + data.msg;
    messagesList.appendChild(listItem);
    sendInput.value = '';
  }
}</pre>

<p>What happens here depends on what the <code>action</code> property on the <code>data</code> object is set to:</p>

<ul>
 <li><code>subscribe</code> or <code>init</code> (at both startup and restart, we need to do the same thing in this sample): An {{htmlelement("li")}} element is created, its text content is set to <code>data.name</code> (the name of the subscriber), and it is appended to the subscribers list (a simple {{htmlelement("ul")}} element) so there is visual feedback that a subscriber has (re)joined the chat.</li>
 <li><code>unsubscribe</code>: We loop through the children of the subscribers list, find the one whose text content is equal to <code>data.name</code> (the name of the unsubscriber), and delete that node to provide visual feedback that someone has unsubscribed.</li>
 <li><code>chatMsg</code>: In a similar manner to the first case, an {{htmlelement("li")}} element is created, its text content is set to <code>data.name + ": " + data.msg</code> (so for example "Chris: This is my message"), and it is appended to the chat messages list; this is how the chat messages appear on the UI for each user.</li>
</ul>

<div class="note">
<p><strong>Note</strong>: We have to pass the data back to the main context before we do DOM updates because service workers don't have access to the DOM. You should be aware of the limitations of service workers before attemping to ue them. Read <a href="/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers">Using Service Workers</a> for more details.</p>
</div>

<h4 id="Sending_chat_messages">Sending chat messages</h4>

<p>When the <em>Send Chat Message</em> button is clicked, the content of the associated text field is sent as a chat message. This is handled by the <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/main.js"><code>sendChatMessage()</code> function</a> (again, not shown in full for brevity). This works in a similar way to the different parts of the <code>updateStatus()</code> function (see {{anch("Updating the status in the app and server")}}) — we retrieve an endpoint and public key via a {{domxref("PushSubscription")}} object, which is itself retrieved via {{domxref("ServiceWorkerContainer.ready()")}} and {{domxref("PushManager.subscribe()")}}. These are sent to the server via {{domxref("XMLHttpRequest")}} in a message object, along with the name of the subscribed user, the chat message to send, and a <code>statusType</code> of <code>chatMsg</code>.</p>

<h3 id="The_server">The server</h3>

<p>As mentioned above, we need a server-side component in our app, to handle storing subscription details, and send out push messages when updates occur. We've hacked together a quick-and-dirty server using <a href="http://nodejs.org/">NodeJS</a> (<code><a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/server.js">server.js</a></code>), which handles the XHR requests sent by our client-side JavaScript code.</p>

<p>It uses a text file (<code><a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/endpoint.txt">endpoint.txt</a></code>) to store subscription details; this file starts out empty. There are four different types of request, marked by the <code>statusType</code> property of the object sent over in the request; these are the same as those understood client-side, and perform the required server actions for that same situation. Here's what each means in the context of the server:</p>

<ul>
 <li><code>subscribe</code>: The server adds the new subscriber's details into the subscription data store (<code><a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/endpoint.txt">endpoint.txt</a></code>), including the endpoint, and then sends a push message to all the endpoints it has stored to tell each subscriber that someone new has joined the chat.</li>
 <li><code>unsubscribe</code>: The server finds the sending subscriber's details in the subscription store and removes it, then sends a push message to all remaining subscribers telling them the user has unsubscribed.</li>
 <li><code>init</code>: The server reads all the current subscribers from the text file, and sends each one a push message to tell them a user has initialized (rejoined) the chat.</li>
 <li><code>chatMsg</code>: Sent by a subscriber that wishes to deliver a message to all users; the server reads the list of all current subscribers from the subscription store file, then sends each one a push message containing the new chat message they should display.</li>
</ul>

<p>A couple more things to note:</p>

<ul>
 <li>We are using the Node.js <a href="https://nodejs.org/api/https.html">https module</a> to create the server, because for security purposes, service workers only work on a secure connection. This is why we need to include the <code>.pfx</code> security cert in the app, and reference it when creating the server in the Node code.</li>
 <li>When you send a push message without data, you simply send it to the endpoint URL using an HTTP <code>POST</code> request. However, when the push message contains data, you need to encrypt it, which is quite a complex process. As time goes on, libraries will appear to do this kind of thing for you; for this demo we used Marco Castelluccio's NodeJS <a href="https://github.com/marco-c/web-push">web-push library</a>. Have a look at the source code to get more of an idea of how the encryption is done (and read <a href="https://tools.ietf.org/html/draft-ietf-webpush-encryption-01">Message Encryption for Web Push</a> for more details.) The library <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/server.js#L43-L46">makes sending a push message simple</a>.</li>
</ul>

<h3 id="The_service_worker">The service worker</h3>

<p>Now let's have a look at the service worker code (<code><a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/sw.js">sw.js</a></code>), which responds to the push messages, represented by {{Event("push")}} events. These are handled on the service worker's scope by the ({{domxref("ServiceWorkerGlobalScope.onpush")}}) event handler; its job is to work out what to do in response to each received message. We first convert the received message back into an object by calling {{domxref("PushMessageData.json()")}}. Next, we check what type of push message it is, by looking at the object's <code>action</code> property:</p>

<ul>
 <li><code>subscribe</code> or <code>unsubscribe</code>: We send a system notification via the <code>fireNotification()</code> function, but also send a message back to the main context on our {{domxref("MessageChannel")}} so we can update the subscriber list accordingly (see {{anch("Handling channel messages sent from the service worker")}} for more details).</li>
 <li><code>init</code> or <code>chatMsg</code>: We just send a channel message back to the main context to handle the <code>init</code> and <code>chatMsg</code> cases (these don't need a system notification).</li>
</ul>

<pre class="brush: js">self.addEventListener('push', function(event) {
  var obj = event.data.json();

  if(obj.action === 'subscribe' || obj.action === 'unsubscribe') {
    fireNotification(obj, event);
    port.postMessage(obj);
  } else if(obj.action === 'init' || obj.action === 'chatMsg') {
    port.postMessage(obj);
  }
});</pre>

<p>Next, let's look at the <code>fireNotification()</code> function (which is blissfully pretty simple).</p>

<pre class="brush: js">function fireNotification(obj, event) {
  var title = 'Subscription change';
  var body = obj.name + ' has ' + obj.action + 'd.';
  var icon = 'push-icon.png';
  var tag = 'push';

  event.waitUntil(self.registration.showNotification(title, {
    body: body,
    icon: icon,
    tag: tag
  }));
}</pre>

<p>Here we assemble the assets needed by the notification box: the title, body, and icon. Then we send a notification via the {{domxref("ServiceWorkerRegistration.showNotification()")}} method, providing that information as well as the tag "push", which we can use to identify this notification among any other notifications we might be using. When the notification is successfully sent, it manifests as a system notification dialog on the users computers/devices in whatever style system notifications look like on those systems (the following image shows a Mac OSX system notification.)</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/11855/subscribe-notification.png" style="display: block; height: 65px; margin: 0px auto; width: 326px;"></p>

<p>Note that we do this from inside an {{domxref("ExtendableEvent.waitUntil()")}} method; this is to make sure the service worker remains active until the notification has been sent. <code>waitUntil()</code> will extend the life cycle of the service worker until everything inside this method has completed.</p>

<div class="note">
<p><strong>Note</strong>: Web notifications from service workers were introduced around Firefox version 42, but are likely to be removed again while the surrounding functionality (such as <code>Clients.openWindow()</code>) is properly implemented (see {{bug(1203324)}} for more details.)</p>
</div>

<h2 id="Handling_premature_subscription_expiration">Handling premature subscription expiration</h2>

<p>Sometimes push subscriptions expire prematurely, without {{domxref("PushSubscription.unsubscribe()")}} being called. This can happen when the server gets overloaded, or if you are offline for a long time, for example.  This is highly server-dependent, so the exact behavior is difficult to predict. In any case, you can handle this problem by watching for the {{Event("pushsubscriptionchange")}} event, which you can listen for by providing a {{domxref("ServiceWorkerGlobalScope.onpushsubscriptionchange")}} event handler; this event is fired only in this specific case.</p>

<pre class="brush: js  language-js"><code class="language-js">self<span class="punctuation token">.</span><span class="function token">addEventListener<span class="punctuation token">(</span></span><span class="string token">'pushsubscriptionchange'</span><span class="punctuation token">,</span> <span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span>
 <span class="comment token"> // do something, usually resubscribe to push and
</span> <span class="comment token"> // send the new subscription details back to the
</span> <span class="comment token"> // server via XHR or Fetch
</span><span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>

<p>Note that we don't cover this case in our demo, as a subscription ending is not a big deal for a simple chat server. But for a more complex example you'd probably want to resubscribe the user.</p>

<h2 id="Extra_steps_for_Chrome_support">Extra steps for Chrome support</h2>

<p>To get the app working on Chrome, we need a few extra steps, as Chrome currently relies on Google's Cloud Messaging service to work.</p>

<h3 id="Setting_up_Google_Cloud_Messaging">Setting up Google Cloud Messaging</h3>

<p>To get this set up, follow these steps:</p>

<ol>
 <li>Navigate to the <a href="https://console.developers.google.com">Google Developers Console</a>  and set up a new project.</li>
 <li>Go to your project's homepage (ours is at <code>https://console.developers.google.com/project/push-project-978</code>, for example), then
  <ol>
   <li>Select the <em>Enable Google APIs for use in your apps</em> option.</li>
   <li>In the next screen, click <em>Cloud Messaging for Android</em> under the <em>Mobile APIs</em> section.</li>
   <li>Click the <em>Enable API</em> button.</li>
  </ol>
 </li>
 <li>Now you need to make a note of your project number and API key because you'll need them later. To find them:
  <ol>
   <li><strong>Project number</strong>: click <em>Home</em> on the left; the project number is clearly marked at the top of your project's home page.</li>
   <li><strong>API key</strong>: click <em>Credentials</em> on the left hand menu; the API key can be found on that screen.</li>
  </ol>
 </li>
</ol>

<h3 id="manifest.json">manifest.json</h3>

<p>You need to include a Google app-style <code>manifest.json</code> file in your app, which references the project number you made a note of earlier in the <code>gcm_sender_id</code> parameter. Here is our simple example <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/manifest.json">manifest.json</a>:</p>

<pre class="brush: js">{
  "name": "Push Demo",
  "short_name": "Push Demo",
  "icons": [{
        "src": "push-icon.png",
        "sizes": "111x111",
        "type": "image/png"
      }],
  "start_url": "/index.html",
  "display": "standalone",
  "gcm_sender_id": "224273183921"
}</pre>

<p>You also need to reference your manifest using a {{HTMLElement("link")}} element in your HTML:</p>

<pre class="brush: html">&lt;link rel="manifest" href="manifest.json"&gt;</pre>

<h3 id="userVisibleOnly">userVisibleOnly</h3>

<p>Chrome requires you to set the <a href="/en-US/docs/Web/API/PushManager/subscribe#Parameters"><code>userVisibleOnly</code> parameter</a> to <code>true</code> when subscribing to the push service, which indicates that we are promising to show a notification whenever a push is received. This can be <a href="https://github.com/chrisdavidmills/push-api-demo/blob/gh-pages/main.js#L127">seen in action in our <code>subscribe()</code> function</a>.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/Push_API">Push API</a></li>
 <li><a href="/en-US/docs/Web/API/Service_Worker_API">Service Worker API</a></li>
</ul>

<div class="note">
<p><strong>Note</strong>: Some of the client-side code in our Push demo is heavily influenced by Matt Gaunt's excellent examples in <a href="http://updates.html5rocks.com/2015/03/push-notificatons-on-the-open-web">Push Notifications on the Open Web</a>. Thanks for the awesome work, Matt!</p>
</div>