Pigeon (Pigeon v2.0.0-rc.0) View Source

HTTP2-compliant wrapper for sending iOS and Android push notifications.

Getting Started

Check the module documentation for your push notification service.

Pigeon.ADM - Amazon Android.
Pigeon.APNS - Apple iOS.
Pigeon.FCM - Firebase Cloud Messaging v1 API.
Pigeon.LegacyFCM - Firebase Cloud Messaging Legacy API.

Creating Dynamic Runtime Dispatchers

Pigeon can spin up dynamic dispatchers for a variety of advanced use-cases, such as supporting dozens of dispatcher configurations or custom connection pools.

See Pigeon.Dispatcher for instructions.

Writing a Custom Dispatcher Adapter

Want to write a Pigeon adapter for an unsupported push notification service?

See Pigeon.Adapter for instructions.

Link to this section Summary

Types

notification()

on_response()

Async callback for push notifications response.

push_opts()

Options for sending push notifications.

Functions

default_pool_size()

Returns the configured default pool size for Pigeon dispatchers. To customize this value, include the following in your config/config.exs

json_library()

Returns the configured JSON encoding library for Pigeon. To customize the JSON library, include the following in your config/config.exs

push(pid, notifications, opts \\ [])

Link to this section Types

notification()

Specs

notification() :: %{__meta__: Pigeon.Metadata.t()}

on_response()

Specs

on_response() ::
  (notification() -> no_return())
  | {module(), atom()}
  | {module(), atom(), [any()]}

Async callback for push notifications response.

Examples

handler = fn(%Pigeon.ADM.Notification{response: response}) ->
  case response do
    :success ->
      Logger.debug "Push successful!"
    :unregistered ->
      Logger.error "Bad device token!"
    _error ->
      Logger.error "Some other error happened."
  end
end

n = Pigeon.ADM.Notification.new("token", %{"message" => "test"})
Pigeon.ADM.push(n, on_response: handler)

push_opts()

Specs

push_opts() :: [on_response: on_response() | nil, timeout: non_neg_integer()]

Options for sending push notifications.

:on_response - Optional async callback triggered on receipt of push. See on_response/0
:timeout - Push timeout. Defaults to 5000ms.

Link to this section Functions

default_pool_size()

Specs

default_pool_size() :: pos_integer()

Returns the configured default pool size for Pigeon dispatchers. To customize this value, include the following in your config/config.exs:

config :pigeon, :default_pool_size, 5

json_library()

Specs

json_library() :: module()

Returns the configured JSON encoding library for Pigeon. To customize the JSON library, include the following in your config/config.exs:

config :pigeon, :json_library, Jason

push(pid, notifications, opts \\ [])

Specs

push(pid() | atom(), notification :: notification(), push_opts()) ::
  notification :: struct() | no_return()

push(pid() | atom(), notifications :: [notification(), ...], push_opts()) ::
  notifications :: [struct(), ...] | no_return()