View Source Pigeon (Pigeon v2.0.0)

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

Getting Started

Check the module documentation for your push notification service.

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.

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 \\ [])

Sends a push notification with given options.

Types

notification()

@type notification() :: %{
  :__struct__ => atom(),
  :__meta__ => Pigeon.Metadata.t(),
  optional(atom()) => any()
}

on_response()

@type 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()

@type 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.

Functions

default_pool_size()

@spec 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()

@spec 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 \\ [])

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

Sends a push notification with given options.