{"id":50722216,"url":"https://github.com/pushpad/pushpad-ruby","last_synced_at":"2026-06-10T01:02:37.947Z","repository":{"id":68258849,"uuid":"50199467","full_name":"pushpad/pushpad-ruby","owner":"pushpad","description":"Ruby library for sending push notifications from websites and web apps.","archived":false,"fork":false,"pushed_at":"2025-01-17T11:08:46.000Z","size":130,"stargazers_count":8,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-17T12:27:42.704Z","etag":null,"topics":["notifications","web-push"],"latest_commit_sha":null,"homepage":"https://pushpad.xyz","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.txt","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":"2016-01-22T18:27:04.000Z","updated_at":"2025-01-17T11:08:47.000Z","dependencies_parsed_at":"2024-01-22T15:17:22.431Z","dependency_job_id":"0ccb8f4d-39f5-4d43-a6d4-06b29a24d34c","html_url":"https://github.com/pushpad/pushpad-ruby","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pushpad/pushpad-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fpushpad-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fpushpad-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fpushpad-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fpushpad-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pushpad","download_url":"https://codeload.github.com/pushpad/pushpad-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pushpad%2Fpushpad-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34132030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2026-06-10T01:02:36.167Z","updated_at":"2026-06-10T01:02:37.941Z","avatar_url":"https://github.com/pushpad.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pushpad - Web Push Notifications\n\n[![Gem Version](https://badge.fury.io/rb/pushpad.svg)](https://badge.fury.io/rb/pushpad)\n![Build Status](https://github.com/pushpad/pushpad-ruby/workflows/CI/badge.svg)\n\n[Pushpad](https://pushpad.xyz) is a service for sending push notifications from websites and web apps. It uses the **Push API**, which is a standard supported by all major browsers (Chrome, Firefox, Opera, Edge, Safari).\n\nThe notifications are delivered in real time even when the users are not on your website and you can target specific users or send bulk notifications.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'pushpad'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install pushpad\n\n## Getting started\n\nFirst you need to sign up to Pushpad and create a project there.\n\nThen set your authentication credentials:\n\n```ruby\nPushpad.auth_token = '5374d7dfeffa2eb49965624ba7596a09'\nPushpad.project_id = 123 # set it here or pass it as a param to methods later\n```\n\n- `auth_token` can be found in the user account settings. \n- `project_id` can be found in the project settings. If your application uses multiple projects, you can pass the `project_id` as a param to methods (e.g. `notification.deliver_to user, project_id: 123`).\n\n## Collecting user subscriptions to push notifications\n\nYou can subscribe the users to your notifications using the Javascript SDK, as described in the [getting started guide](https://pushpad.xyz/docs/pushpad_pro_getting_started).\n\nIf you need to generate the HMAC signature for the `uid` you can use this helper:\n\n```ruby\nPushpad.signature_for current_user.id\n```\n\n## Sending push notifications\n\n```ruby\nnotification = Pushpad::Notification.new({\n  # required, the main content of the notification\n  body: \"Hello world!\",\n\n  # optional, the title of the notification (defaults to your project name)\n  title: \"Website Name\",\n\n  # optional, open this link on notification click (defaults to your project website)\n  target_url: \"https://example.com\",\n\n  # optional, the icon of the notification (defaults to the project icon)\n  icon_url: \"https://example.com/assets/icon.png\",\n\n  # optional, the small icon displayed in the status bar (defaults to the project badge)\n  badge_url: \"https://example.com/assets/badge.png\",\n\n  # optional, an image to display in the notification content\n  # see https://pushpad.xyz/docs/sending_images\n  image_url: \"https://example.com/assets/image.png\",\n\n  # optional, drop the notification after this number of seconds if a device is offline\n  ttl: 604800,\n\n  # optional, prevent Chrome on desktop from automatically closing the notification after a few seconds\n  require_interaction: true,\n\n  # optional, enable this option if you want a mute notification without any sound\n  silent: false,\n\n  # optional, enable this option only for time-sensitive alerts (e.g. incoming phone call)\n  urgent: false,\n\n  # optional, a string that is passed as an argument to action button callbacks\n  custom_data: \"123\",\n\n  # optional, add some action buttons to the notification\n  # see https://pushpad.xyz/docs/action_buttons\n  actions: [\n    {\n      title: \"My Button 1\",\n      target_url: \"https://example.com/button-link\", # optional\n      icon: \"https://example.com/assets/button-icon.png\", # optional\n      action: \"myActionName\" # optional\n    }\n  ],\n\n  # optional, bookmark the notification in the Pushpad dashboard (e.g. to highlight manual notifications)\n  starred: true,\n\n  # optional, use this option only if you need to create scheduled notifications (max 5 days)\n  # see https://pushpad.xyz/docs/schedule_notifications\n  send_at: Time.utc(2016, 7, 25, 10, 9),\n\n  # optional, add the notification to custom categories for stats aggregation\n  # see https://pushpad.xyz/docs/monitoring\n  custom_metrics: ['examples', 'another_metric'] # up to 3 metrics per notification\n})\n\n# deliver to a user\nnotification.deliver_to user # or user_id\n\n# deliver to a group of users\nnotification.deliver_to users # or user_ids\n\n# deliver to some users only if they have a given preference\n# e.g. only \"users\" who have a interested in \"events\" will be reached\nnotification.deliver_to users, tags: ['events']\n\n# deliver to segments\n# e.g. any subscriber that has the tag \"segment1\" OR \"segment2\"\nnotification.broadcast tags: ['segment1', 'segment2']\n\n# you can use boolean expressions \n# they can include parentheses and the operators !, \u0026\u0026, || (from highest to lowest precedence)\n# https://pushpad.xyz/docs/tags\nnotification.broadcast tags: ['zip_code:28865 \u0026\u0026 !optout:local_events || friend_of:Organizer123']\nnotification.deliver_to users, tags: ['tag1 \u0026\u0026 tag2', 'tag3'] # equal to 'tag1 \u0026\u0026 tag2 || tag3'\n\n# deliver to everyone\nnotification.broadcast\n```\n\nYou can set the default values for most fields in the project settings. See also [the docs](https://pushpad.xyz/docs/rest_api#notifications_api_docs) for more information about notification fields.\n\nIf you try to send a notification to a user ID, but that user is not subscribed, that ID is simply ignored.\n\nThe methods above return an hash:\n\n- `\"id\"` is the id of the notification on Pushpad\n- `\"scheduled\"` is the estimated reach of the notification (i.e. the number of devices to which the notification will be sent, which can be different from the number of users, since a user may receive notifications on multiple devices)\n- `\"uids\"` (`deliver_to` only) are the user IDs that will be actually reached by the notification because they are subscribed to your notifications. For example if you send a notification to `['uid1', 'uid2', 'uid3']`, but only `'uid1'` is subscribed, you will get `['uid1']` in response. Note that if a user has unsubscribed after the last notification sent to him, he may still be reported for one time as subscribed (this is due to [the way](https://blog.pushpad.xyz/2016/05/the-push-api-and-its-wild-unsubscription-mechanism/) the W3C Push API works).\n- `\"send_at\"` is present only for scheduled notifications. The fields `\"scheduled\"` and `\"uids\"` are not available in this case.\n\nThe `id` and `scheduled_count` attribute are also stored on the notification object:\n\n```ruby\n\nnotification.deliver_to user\n\nnotification.id # =\u003e 1000\nnotification.scheduled_count # =\u003e 5\n```\n\n## Getting push notification data\n\nYou can retrieve data for past notifications:\n\n```ruby\nnotification = Pushpad::Notification.find(42)\n\n# get basic attributes\nnotification.id # =\u003e 42\nnotification.title # =\u003e \"Foo Bar\"\nnotification.body # =\u003e \"Lorem ipsum dolor sit amet, consectetur adipiscing elit.\"\nnotification.target_url # =\u003e \"https://example.com\"\nnotification.ttl # =\u003e 604800\nnotification.require_interaction # =\u003e false\nnotification.silent # =\u003e false\nnotification.urgent # =\u003e false\nnotification.icon_url # =\u003e \"https://example.com/assets/icon.png\"\nnotification.badge_url # =\u003e \"https://example.com/assets/badge.png\"\n\n# `created_at` is a `Time` instance\nnotification.created_at.utc.to_s # =\u003e \"2016-07-06 10:09:14 UTC\"\n\n# get statistics\nnotification.scheduled_count # =\u003e 1\nnotification.successfully_sent_count # =\u003e 4\nnotification.opened_count # =\u003e 2\n```\n\nOr for mutliple notifications of a project at once:\n\n```ruby\nnotifications = Pushpad::Notification.find_all(project_id: 5)\n\n# same attributes as for single notification in example above\nnotifications[0].id # =\u003e 42\nnotifications[0].title # =\u003e \"Foo Bar\"\n```\n\nIf `Pushpad.project_id` is defined, the `project_id` option can be\nomitted.\n\nThe REST API paginates the result set. You can pass a `page` parameter\nto get the full list in multiple requests.\n\n```ruby\nnotifications = Pushpad::Notification.find_all(project_id: 5, page: 2)\n```\n\n## Scheduled notifications\n\nYou can create scheduled notifications that will be sent in the future:\n\n```ruby\nnotification = Pushpad::Notification.new({\n  body: \"This notification will be sent after 60 seconds\",\n  send_at: Time.now.utc + 60\n})\n\nnotification.broadcast\n```\n\nYou can also cancel a scheduled notification:\n\n```ruby\nnotification = Pushpad::Notification.find(5)\nnotification.cancel\n```\n\n## Getting subscription count\n\nYou can retrieve the number of subscriptions for a given project,\noptionally filtered by `tags` or `uids`:\n\n```ruby\nPushpad::Subscription.count(project_id: 5) # =\u003e 100\nPushpad::Subscription.count(project_id: 5, uids: ['user1']) # =\u003e 2\nPushpad::Subscription.count(project_id: 5, tags: ['sports']) # =\u003e 10\nPushpad::Subscription.count(project_id: 5, tags: 'sports \u0026\u0026 travel') # =\u003e 5\nPushpad::Subscription.count(project_id: 5, uids: ['user1'], tags: 'sports \u0026\u0026 travel') # =\u003e 1\n```\n\nIf `Pushpad.project_id` is defined, the `project_id` option can be\nomitted.\n\n## Getting push subscription data\n\nYou can retrieve the subscriptions for a given project,\noptionally filtered by `tags` or `uids`:\n\n```ruby\nPushpad::Subscription.find_all(project_id: 5)\nPushpad::Subscription.find_all(project_id: 5, uids: ['user1'])\nPushpad::Subscription.find_all(project_id: 5, tags: ['sports'])\nPushpad::Subscription.find_all(project_id: 5, tags: 'sports \u0026\u0026 travel')\nPushpad::Subscription.find_all(project_id: 5, uids: ['user1'], tags: 'sports \u0026\u0026 travel')\n```\n\nIf `Pushpad.project_id` is defined, the `project_id` option can be\nomitted.\n\nThe REST API paginates the result set. You can pass a `page` parameter\nto get the full list in multiple requests.\n\n```ruby\nsubscriptions = Pushpad::Subscription.find_all(project_id: 5, page: 2)\n```\n\nYou can also retrieve the data of a specific subscription if you already know its id:\n\n```ruby\nPushpad::Subscription.find 123\nPushpad::Subscription.find 123, project_id: 456\n```\n\n## Updating push subscription data\n\nUsually you add data, like user IDs and tags, to the push subscriptions using the [JavaScript SDK](https://pushpad.xyz/docs/javascript_sdk_reference) in the frontend.\n\nHowever you can also update the subscription data from your server:\n\n```ruby\nPushpad::Subscription.find_all(uids: ['user1']).each do |subscription|\n  # update the user ID associated to the push subscription\n  subscription.update uid: 'myuser1'\n  \n  # update the tags associated to the push subscription\n  tags = subscription.tags\n  tags \u003c\u003c 'another_tag'\n  subscription.update tags: tags\nend\n```\n\n## Importing push subscriptions\n\nIf you need to [import](https://pushpad.xyz/docs/import) some existing push subscriptions (from another service to Pushpad, or from your backups) or if you simply need to create some test data, you can use this method:\n\n```ruby\nattributes = {\n  endpoint: \"https://example.com/push/f7Q1Eyf7EyfAb1\", \n  p256dh: \"BCQVDTlYWdl05lal3lG5SKr3VxTrEWpZErbkxWrzknHrIKFwihDoZpc_2sH6Sh08h-CacUYI-H8gW4jH-uMYZQ4=\",\n  auth: \"cdKMlhgVeSPzCXZ3V7FtgQ==\",\n  uid: \"exampleUid\", \n  tags: [\"exampleTag1\", \"exampleTag2\"]\n}\n\nsubscription = Pushpad::Subscription.create(attributes, project_id: 5)\n```\n\nPlease note that this is not the standard way to collect subscriptions on Pushpad: usually you subscribe the users to the notifications using the [JavaScript SDK](https://pushpad.xyz/docs/javascript_sdk_reference) in the frontend.\n\n## Deleting push subscriptions\n\nUsually you unsubscribe a user from push notifications using the [JavaScript SDK](https://pushpad.xyz/docs/javascript_sdk_reference) in the frontend (recommended).\n\nHowever you can also delete the subscriptions using this library. Be careful, the subscriptions are permanently deleted!\n\n```ruby\nsubscription = Pushpad::Subscription.find 123\nsubscription.delete\n```\n\n## Managing projects\n\nProjects are usually created manually from the Pushpad dashboard. However you can also create projects from code if you need advanced automation or if you manage [many different domains](https://pushpad.xyz/docs/multiple_domains).\n\n```ruby\nattributes = {\n  # required attributes\n  sender_id: 123,\n  name: \"My project\",\n  website: \"https://example.com\",\n  \n  # optional configurations\n  icon_url: \"https://example.com/icon.png\",\n  badge_url: \"https://example.com/badge.png\",\n  notifications_ttl: 604800,\n  notifications_require_interaction: false,\n  notifications_silent: false\n}\n\nproject = Pushpad::Project.create(attributes)\n```\n\nYou can also find, update and delete projects:\n\n```ruby\nPushpad::Project.find_all.each do |p|\n  puts \"Project #{p.id}: #{p.name}\"\nend\n\nproject = Pushpad::Project.find 123\n\nproject.update(name: 'The New Project Name')\n\nproject.delete\n```\n\n## Managing senders\n\nSenders are usually created manually from the Pushpad dashboard. However you can also create senders from code.\n\n```ruby\nattributes = {\n  # required attributes\n  name: \"My sender\",\n  \n  # optional configurations\n  # do not include these fields if you want to generate them automatically\n  vapid_private_key: \"-----BEGIN EC PRIVATE KEY----- ...\",\n  vapid_public_key: \"-----BEGIN PUBLIC KEY----- ...\"\n}\n\nsender = Pushpad::Sender.create(attributes)\n```\n\nYou can also find, update and delete senders:\n\n```ruby\nPushpad::Sender.find_all.each do |s|\n  puts \"Sender #{s.id}: #{s.name}\"\nend\n\nsender = Pushpad::Sender.find 987\n\nsender.update(name: 'The New Sender Name')\n\nsender.delete\n```\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushpad%2Fpushpad-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpushpad%2Fpushpad-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpushpad%2Fpushpad-ruby/lists"}