{"id":13878176,"url":"https://github.com/pushpad/web-push","last_synced_at":"2025-07-16T14:31:36.359Z","repository":{"id":63816096,"uuid":"570844133","full_name":"pushpad/web-push","owner":"pushpad","description":"Web Push library for Ruby (RFC8030) - A fork of zaru/webpush actively maintained by Pushpad with many improvements, bug fixes and updates.","archived":false,"fork":false,"pushed_at":"2024-06-25T15:21:30.000Z","size":200,"stargazers_count":144,"open_issues_count":3,"forks_count":14,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-08T23:41:53.771Z","etag":null,"topics":["notifications","web-push"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pushpad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-26T10:09:36.000Z","updated_at":"2024-11-08T11:42:35.000Z","dependencies_parsed_at":"2024-06-19T01:35:20.637Z","dependency_job_id":"84cc5a73-df47-448f-bce3-ad59ce4b19aa","html_url":"https://github.com/pushpad/web-push","commit_stats":{"total_commits":192,"total_committers":23,"mean_commits":8.347826086956522,"dds":0.75,"last_synced_commit":"5326a5f420736cb2aaf3cf8b1fe8eaa1806a1923"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fweb-push","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fweb-push/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fweb-push/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fweb-push/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pushpad","download_url":"https://codeload.github.com/pushpad/web-push/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226138849,"owners_count":17579496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["notifications","web-push"],"created_at":"2024-08-06T08:01:41.929Z","updated_at":"2024-11-24T07:30:49.547Z","avatar_url":"https://github.com/pushpad.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# WebPush\n\n[![Gem Version](https://badge.fury.io/rb/web-push.svg)](https://badge.fury.io/rb/web-push)\n![Build Status](https://github.com/pushpad/web-push/workflows/CI/badge.svg)\n\nThis gem makes it possible to send push messages to web browsers from Ruby backends using the [Web Push Protocol](https://datatracker.ietf.org/doc/html/rfc8030). It supports [Message Encryption for Web Push](https://datatracker.ietf.org/doc/html/rfc8291) and [VAPID](https://datatracker.ietf.org/doc/html/rfc8292).\n\n**Note**: This is an open source gem for Web Push. If you want to send web push notifications from Ruby using Pushpad, you need to use another gem ([pushpad gem](https://github.com/pushpad/pushpad-ruby)).\n\n## Installation\n\nAdd this line to the Gemfile:\n\n```ruby\ngem 'web-push'\n```\n\nOr install the gem:\n\n```console\n$ gem install web-push\n```\n\n## Usage\n\nSending a web push message to a visitor of your website requires a number of steps:\n\n1. In the user's web browser, a `serviceWorker` is installed and activated and its `pushManager` property is subscribed to push events with your VAPID public key, which creates a `subscription` JSON object on the client side.\n2. Your server uses the `web-push` gem to send a notification with the `subscription` obtained from the client and an optional payload (the message).\n3. Your service worker is set up to receive `'push'` events. To trigger a desktop notification, the user has accepted the prompt to receive notifications from your site.\n\n### Generating VAPID keys\n\nUse `web-push` to generate a VAPID key pair (that has both a `public_key` and `private_key`) and save it on the server side.\n\n```ruby\n# One-time, on the server\nvapid_key = WebPush.generate_key\n\n# Save these in your application server settings\nvapid_key.public_key\nvapid_key.private_key\n\n# Or you can save in PEM format if you prefer\nvapid_key.to_pem\n```\n\n### Installing a service worker\n\nYour application must use JavaScript to register a service worker script at an appropriate scope (root is recommended).\n\n```javascript\nnavigator.serviceWorker.register('/service-worker.js')\n```\n\n### Subscribing to push notifications\n\nThe VAPID public key that you generated earlier needs to be made available to JavaScript, which can be done in many ways, for example with a fetch request or when rendering the HTML template in Ruby:\n\n```erb\n\u003cscript\u003e\n// Make the VAPID public key available to the client as a Uint8Array\nwindow.vapidPublicKey = new Uint8Array(\u003c%= Base64.urlsafe_decode64(ENV['VAPID_PUBLIC_KEY']).bytes %\u003e)\n\n// Or you can pass it as a string if you prefer\nwindow.vapidPublicKey = \"\u003c%= ENV['VAPID_PUBLIC_KEY'].delete('=') %\u003e\"\n\u003c/script\u003e\n```\n\nYour JavaScript code uses the `pushManager` interface to subscribe to push notifications, passing the VAPID public key to the subscription settings.\n\n```javascript\n// When serviceWorker is supported, installed, and activated,\n// subscribe the pushManager property with the vapidPublicKey\nnavigator.serviceWorker.ready.then((serviceWorkerRegistration) =\u003e {\n  serviceWorkerRegistration.pushManager\n  .subscribe({\n    userVisibleOnly: true,\n    applicationServerKey: window.vapidPublicKey\n  });\n});\n```\n\n### Triggering a web push notification\n\nIn order to send web push notifications, the push subscription must be stored in the backend. Get the subscription with `pushManager.getSubscription()` and store it in your database.\n\nThen you can use this gem to send web push messages:\n\n```ruby\nWebPush.payload_send(\n  message: message,\n  endpoint: subscription['endpoint'],\n  p256dh: subscription['keys']['p256dh'],\n  auth: subscription['keys']['auth'],\n  vapid: {\n    subject: \"mailto:sender@example.com\",\n    public_key: ENV['VAPID_PUBLIC_KEY'],\n    private_key: ENV['VAPID_PRIVATE_KEY']\n  },\n  ssl_timeout: 5, # optional value for Net::HTTP#ssl_timeout=\n  open_timeout: 5, # optional value for Net::HTTP#open_timeout=\n  read_timeout: 5 # optional value for Net::HTTP#read_timeout=\n)\n```\n\n### Receiving the push event\n\nYour `service-worker.js` script should respond to `'push'` events. One action it can take is to trigger desktop notifications by calling `showNotification` on the `registration` property.\n\n```javascript\nself.addEventListener('push', (event) =\u003e {\n  // Get the push message\n  var message = event.data;\n  // Display a notification\n  event.waitUntil(self.registration.showNotification('Example'));\n});\n```\n\nBefore the notifications can be displayed, the user must grant permission for [notifications](https://developer.mozilla.org/en-US/docs/Web/API/notification) in a browser prompt. Use something like this in your JavaScript code:\n\n```javascript\nNotification.requestPermission();\n```\n\nIf everything worked, you should see a desktop notification triggered via web push. Yay!\n\n## API\n\n### With a payload\n\n```ruby\nmessage = {\n  title: \"Example\",\n  body: \"Hello, world!\",\n  icon: \"https://example.com/icon.png\"\n}\n\nWebPush.payload_send(\n  endpoint: \"https://fcm.googleapis.com/gcm/send/eah7hak....\",\n  message: JSON.generate(message),\n  p256dh: \"BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...\",\n  auth: \"aW1hcmthcmFpa3V6ZQ==\",\n  ttl: 600, # optional, ttl in seconds, defaults to 2419200 (4 weeks)\n  urgency: 'normal' # optional, it can be very-low, low, normal, high, defaults to normal\n)\n```\n\n### Without a payload\n\n```ruby\nWebPush.payload_send(\n  endpoint: \"https://fcm.googleapis.com/gcm/send/eah7hak....\",\n  p256dh: \"BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...\",\n  auth: \"aW1hcmthcmFpa3V6ZQ==\"\n)\n```\n\n### With VAPID\n\nVAPID details are given as a hash with `:subject`, `:public_key`, and\n`:private_key`. The `:subject` is a contact URI for the application server as either a \"mailto:\" or an \"https:\" address. The `:public_key` and `:private_key` should be passed as the base64-encoded values generated with `WebPush.generate_key`.\n\n```ruby\nWebPush.payload_send(\n  endpoint: \"https://fcm.googleapis.com/gcm/send/eah7hak....\",\n  message: \"A message\",\n  p256dh: \"BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...\",\n  auth: \"aW1hcmthcmFpa3V6ZQ==\",\n  vapid: {\n    subject: \"mailto:sender@example.com\",\n    public_key: ENV['VAPID_PUBLIC_KEY'],\n    private_key: ENV['VAPID_PRIVATE_KEY']\n  }\n)\n```\n\n### With VAPID in PEM format\n\nThis library also supports the PEM format for the VAPID keys:\n\n```ruby\nWebPush.payload_send(\n  endpoint: \"https://fcm.googleapis.com/gcm/send/eah7hak....\",\n  message: \"A message\",\n  p256dh: \"BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...\",\n  auth: \"aW1hcmthcmFpa3V6ZQ==\",\n  vapid: {\n    subject: \"mailto:sender@example.com\",\n    pem: ENV['VAPID_KEYS']\n  }\n)\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/pushpad/web-push.\n\n## Credits\n\nThis library is a fork of [zaru/webpush](https://github.com/zaru/webpush) actively maintained by [Pushpad](https://pushpad.xyz) with many improvements, bug fixes and frequent updates.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushpad%2Fweb-push","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpushpad%2Fweb-push","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushpad%2Fweb-push/lists"}