Skip to content

README.md

Latest commit

 

History

History
111 lines (79 loc) · 3.1 KB

README.md

File metadata and controls

111 lines (79 loc) · 3.1 KB

Web Push Elixir

Simple web push library for Elixir

Test Status Code Coverage Hex Version Hex Docs

Prerequisities

  • Elixir 1.18
  • OTP 26 / 27 / 28

Installation

  1. Add web_push_elixir to your list of dependencies in mix.exs:
def deps do
  [
    {:web_push_elixir, "~> 0.5.0"}
  ]
end
  1. Run mix command to generate your Vapid public and private keys:
mix generate.vapid.keys
  1. Set config for your generated keys:
config :web_push_elixir,
  vapid_public_key: "someVapidPublicKey",
  vapid_private_key: "someVapidPrivateKey",
  vapid_subject: "mailto:[email protected]"

Usage

WebPushElixir provides a simple send_notification/2 that takes 2 arguments:

  • subscription: the subscription information received from the client - example demo
  • message: the message string.
subscription = '{"endpoint":"https://some-push-service","keys":{"p256dh":"BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM=","auth":"tBHItJI5svbpez7KI4CCXg=="}}'
message = "Some message"

WebPushElixir.send_notification(subscription, message)

For more information on how to subscribe a client, permission UX and more - take a look at https://web.dev/notifications/

Error Handling

WebPushElixir returns error types to help you handle failures:

case WebPushElixir.send_notification(subscription, message) do
  {:ok, _response} ->
    # Notification sent successfully
    :ok
  
  {:error, :expired} ->
    # Subscription expired or not found (HTTP 404 / 410)
    Repo.delete(subscription)
  
  {:error, {:http_error, status, body}} ->
    # Handle specific HTTP errors from the push service
    Logger.error("Push notification failed: HTTP #{status} - #{body}")
end

Common Web Push HTTP Status Codes

  • 200-202: Success
  • 404: Subscription not found
  • 410: Subscription expired (user revoked permission)
  • 400: Bad request (invalid parameters or VAPID headers)
  • 401 / 403: Authentication error (check VAPID configuration)
  • 413: Payload too large (max 3kB)
  • 429: Rate limited (retry later)
  • 500: Server error (retry later)

Run tests

mix test

License

Web Push Elixir is open-sourced software licensed under the MIT license.

Credits

Heavily inspired by elixir-web-push-encryption