Pigeon - iOS and Android push notifications for Elixir

hpopp · October 1, 2017, 7:23pm

After just over two years in development, this latest version of Pigeon is what I finally consider done in regards to my original vision for the project. v1.1 brings several needed API-breaking changes that should have been rolled into v1.0, but were otherwise overshadowed by the complexity of the FCM http2 implementation. Special thanks to @talklittle for his help on this release.

What is Pigeon? It’s a library for sending iOS, Android, and Amazon Android push notifications. Check out the project: https://github.com/codedge-llc/pigeon

What’s New

Kadabra Bumped to v0.3.2

Kadabra is an HTTP/2 client I wrote from scratch specifically to support Pigeon. v0.3+ brings significant stability improvements (and might actually run a bit faster). This bumps the minimum requirements to Elixir v1.4 and OTP 19.2

Runtime Worker Configs

APNS/FCM/ADM worker connections are now started with custom structs. The old config style is still valid, but it is recommended to use the new style.

# config.exs
config :pigeon, workers: [
  {YourApp.Pigeon, :apns_config},
  ...
]

# your_app_pigeon.ex
defmodule YourApp.Pigeon do
  def apns_config do
    Pigeon.APNS.Config.new(
      name: :apns_default,
      mode: :prod,
      cert: System.get_env("APNS_CERT"),
      key: System.get_env("APNS_KEY"),
      reconnect: false,
      port: 2197,
      ping_period: 300_000
    )
  end
end

Note: :apns_default, :fcm_default, and :adm_default still need to be specified as names in your config if you want pigeon to push to them by default.

Standardized Notification Responses

Notifications now contain the push response on the notification itself. This makes sending batches of notifications more straightforward. APNS and ADM now have a :response key indicating success or failure.

FCM.NotificationResponse has been done away in favor of this new style, though the syntax is a bit different. :response is a keyword list of [{response, "reg id"}] for per-regID responses. There is a second :status key on the notification that indicates whether the whole batch was successful.

Example usage for async response handling on FCM

def handle_response(%FCM.Notification{status: :success, response: responses}) do
  Enum.map(responses, & handle_regid(&1))
end
def handle_response(_else) do
  # some sort of error
end

def handle_regid({:update, {old, new}), do: #update
def handle_regid({:invalid_registration, regid), do: #remove
def handle_regid({:not_registered, regid}), do: #remove
def handle_regid({:unavailable, regid), do: #retry
...

FCM.push(notif, on_response: &handle_response/1)

Roadmap Ahead

Forcus is now going to shift to tackling some of the smaller features that have been on the backburner. Among these:

JWT token support for APNS
Topic subscriptions for FCM
Better onboarding for contributors (mock APNS servers anyone?)

Thanks to everyone who has contributed to the project over the past couple years. As someone who was previously never very involved with open source, I feel like I’ve learned a lot in the process.

talklittle · October 2, 2017, 1:30am

Congratulations @hpopp! Just wanted to say you’re doing a great job as the maintainer of Pigeon, and collaborating with you on pull requests and issues has been a pleasure.

Also I’ve been running Pigeon in production for nearly a year, and it’s been pretty stable, not to mention a breeze to set up. Thanks for your contributions to the Elixir ecosystem!

kokolegorille · October 2, 2017, 1:38am

Does pigeon implement the full IPoAC Protocol?

hpopp · October 2, 2017, 2:10am

Maybe in a future release. I hear supervision is a bit complicated when they die.

hpopp · May 25, 2018, 6:34pm

v1.2.0 Released

Now with support for APNS JWT configuration! Special thanks to @Lankester for the feature.

It’s very simple to configure! Pigeon can auto-detect whether you are using a certificate or token config.

config :pigeon, :apns,
  apns_default: %{
    key: "AuthKey.p8",
    key_identifier: "ABC1234567",
    team_id: "DEF8901234",
    mode: :dev
  }

:key is configured just like :cert, which can be a file path, file contents, string or tuple.

Kadabra Updates

Pigeon now uses Kadabra 0.4.2, which brings more http2 stability improvements. Various race condition errors during connection shutdown should now be fixed!

Roadmap Ahead

The only remaining major feature is FCM web push encryption support. Once implemented, focus will shift to improving the reliability of error handling for failed push notifications. There are certain Kadabra API changes in the works that will make this task much easier. It’s finally starting to mature into a more general purpose http2 client. Take a look at the repo if you haven’t already.

joe · January 6, 2020, 2:46pm

I’m not sure how I am to understand this library. If I have a phoenix “app” which is installed with the “add to home screen” feature of the mobile devices, can I use this library to send the push notifications to those people?

If yes, I need to create this certificate stuff and can then just use it? It’s gonna be creating a service worker and such stuff automatically? Or is this a different thing from this kinda stuff? https://developers.google.com/web/fundamentals/codelabs/push-notifications

I have browsed through the documentation but I feel now more confused than before. So a quick real world example on when I am to use this library would be cool. The how is well described already.

hpopp · January 6, 2020, 4:37pm

I can see why you might be confused, web push notifications were never implemented . Pigeon is used for delivering notifications to native mobile apps (iOS and Android). These are only apps deployed through their respective app stores, and use the standard configuration determined by each mobile platform.

Web push support is still on the eventual list, but it has a different flow from typical mobile push notifications.

tfwright · January 6, 2020, 5:11pm

I had a similar confusion and ended up using this small library to send web push notifications:

It’s been working well for me sending notifications to browsers (and broswer based phone apps).

joe · January 7, 2020, 12:53pm

Okay, cool. Thanks to both of you.

hpopp · July 5, 2021, 6:47pm

Pigeon 2.0.0-rc.0 Released

It’s been a long time coming, but it’s here! A lot of significant updates and new features, including the FCM v1 API with web-push support and better runtime configuration of push workers.

This will serve as an unofficial migration guide until I’ve written one. Feedback is welcome!

Hexdocs available here.

Using the New Worker Setup

Pigeon 1.x uses default expected atom names for workers and supervised all of them independent from your application. This has been done away with for more of an Ecto-style setup in your supervision tree. The following example is for APNS, but it’s a similar strategy for all of your other push workers.

Create an APNS dispatcher.

# lib/apns.ex
defmodule YourApp.APNS do
  use Pigeon.Dispatcher, otp_app: :your_app
end

(Optional) Add configuration to your config.exs. Note the :adapter key, which tells Pigeon what kind of worker you are setting up.

# config.exs

config :your_app, YourApp.APNS,
  adapter: Pigeon.APNS,
  cert: File.read!("cert.pem"),
  key: File.read!("key_unencrypted.pem"),
  mode: :dev

Start your dispatcher on application boot.

defmodule YourApp.Application do
  @moduledoc false

  use Application

  @doc false
  def start(_type, _args) do
    children = [
      YourApp.APNS
    ]
    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

If you skipped step two, include your configuration.

defmodule YourApp.Application do
  @moduledoc false

  use Application

  @doc false
  def start(_type, _args) do
    children = [
      {YourApp.APNS, apns_opts()}
    ]
    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
    Supervisor.start_link(children, opts)
  end

  defp apns_opts do
    [
      adapter: Pigeon.APNS,
      cert: File.read!("cert.pem"),
      key: File.read!("key_unencrypted.pem"),
      mode: :dev
    ]
  end
end

Create a notification.

n = Pigeon.APNS.Notification.new("your message", "your device token", "your push topic")

Send the notification. Note: you use the module name! Not Pigeon.APNS.

YourApp.APNS.push(n)

Using this strategy should make it far more flexible for worker setup, including things like loading dynamic push configurations from a database. See Pigeon.Dispatcher for more instructions.

FCM v1.0 API

All legacy Pigeon.FCM functionality has been renamed to Pigeon.LegacyFCM. You will need to do a project-wide rename, or else update to the new configuration and notification structure.

# Before
Pigeon.FCM.Notification.new("reg ID", %{"body" => "test message"})

# After
Pigeon.LegacyFCM.Notification.new("reg ID", %{"body" => "test message"})

The new Pigeon.FCM.Notification exposes all of the v1 notification attributes you might expect to use, but makes no guarantees about structure and typing, apart from the top-level keys. This gets you maximum flexibility to use the API how you need, including things like custom APNS options or web push.

Notification targets replace the typical RegID string. You now pass a tuple for what you want, such as {:token, "regid"}, {:topic, "yourtopic"}, or {:condition, "yourcondition"}.

Pigeon.FCM.Notification.new({:token, "reg ID"})
%Pigeon.FCM.Notification{
  data: nil,
  notification: nil,
  target: {:token, "reg ID"}
}

Pigeon.FCM.Notification.new({:topic, "example"})
%Pigeon.FCM.Notification{
  data: nil,
  notification: nil,
  target: {:topic, "example"}
}

Notification moduledocs here. You also might want to reference the Firebase v1 Message API as well.

Custom Adapters

Probably the coolest feature of this update is the new Pigeon.Adapter behaviour, which all Pigeon workers implement. What does this mean long term? Anybody can write a push adapter for Pigeon, whether that’s a third party push service, SMS, webhooks, or anything else. Expect better documentation on this soon, but in the meantime if you’re interested in writing an adapter, reach out to me and I can help!

Here is an example of the Pigeon.Sandbox adapter, which is useful for tests and local development. It will mark any push as :success and return it.

defmodule Pigeon.Sandbox do
  import Pigeon.Tasks, only: [process_on_response: 1]

  @behaviour Pigeon.Adapter

  @impl true
  def init(opts \ []) do
    {:ok, opts}
  end

  @impl true
  def handle_info(_msg, state) do
    {:noreply, state}
  end

  @impl true
  def handle_push(%{response: nil} = notification, on_response, _state) do
    process_on_response(on_response, %{notification | response: :success})
    {:noreply, state}
  end

  def handle_push(notification, on_response, state) do
    process_on_response(on_response, notification)
    {:noreply, state}
  end
end

Worker Pooling By Default

Now that APNS allows multiple persistent connections, worker pooling has been enabled by default. The default value is 5 for all services, but this can be overridden on a per-dispatcher basis or globally.

# Just the FCM worker
config :your_app, YourApp.FCM,
  pool_size: 10

# Globally
config :pigeon, :default_pool_size, 10

Next Steps

This release removes a lot of the cruft from design choices that were made in the early days of Pigeon. It is highly encouraged to adopt the new FCM v1 API. Many users of Pigeon jumped through hoops to get dynamic runtime workers started. Feedback is welcome on the new style-- hopefully it’s far more pleasant!

So what’s next feature-wise? Telemetry metrics. Expect it in a 2.1 release!

edisonywh · July 5, 2021, 8:36pm

Awesome! Any plans to add support for other HTTP adapters like Finch?

hpopp · July 12, 2021, 12:03pm

Thanks for the suggestion! Funny enough Pigeon 1.x supported HTTP/2 adapters, but I removed it because I didn’t believe it was being used, and I was never particularly happy with the design.

I should probably prioritize it again in a minor release, but this time in a HTTP/HTTP2 agnostic way. Kadabra is due for a significant refactor, and it will open up more options for how I want to handle it.

ChristophK · March 27, 2023, 7:42am

For the version 1.6.0, what is the your_fcm_key_here? I tried all kind of keys and I get :unauthorized.
I tried the connected Service Account API key, but it doesn’t work either…

ChristophK · March 27, 2023, 8:04am

… just had once more try enabling the legacy API and that has worked now. Didn’t expect that key to be it.