View Source Pigeon.APNS (Pigeon v2.0.0-rc.2)

Pigeon.Adapter for Apple Push Notification Service (APNS) push notifications.

Getting Started

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.

# config.exs

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

Or use token based authentication:

config :your_app, YourApp.APNS,
  adapter: Pigeon.APNS,
  key: File.read!("AuthKey.p8"),
  key_identifier: "ABC1234567",
  mode: :dev,
  team_id: "DEF8901234"

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. Note: Your push topic is generally the app's bundle identifier.

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

Send the packet. Pushes are synchronous and return the notification with an updated :response key.

YourApp.APNS.push(n)

Configuration Options

Certificate Authentication

:cert - Push certificate. Must be the full-text string of the file contents.
:key - Push private key. Must be the full-text string of the file contents.

Token Authentication

:key - JWT private key. Must be the full-text string of the file contents.
:key_identifier - A 10-character key identifier (kid) key, obtained from your developer account.
:team_id - Your 10-character Team ID, obtained from your developer account.

Shared Options

:mode - If set to :dev or :prod, will set the appropriate :uri.
:ping_period - Interval between server pings. Necessary to keep long running APNS connections alive. Defaults to 10 minutes.
:port - Push server port. Can be any value, but APNS only accepts 443 and 2197.
:uri - Push server uri. If set, overrides uri defined by :mode. Useful for test environments.

Generating Your Certificate and Key .pem

In Keychain Access, right-click your push certificate and select "Export..."
Export the certificate as cert.p12
Click the dropdown arrow next to the certificate, right-click the private key and select "Export..."
Export the private key as key.p12
From a shell, convert the certificate.

openssl pkcs12 -legacy -clcerts -nokeys -out cert.pem -in cert.p12

Convert the key. Be sure to set a PEM pass phrase here. The pass phrase must be 4 or more characters in length or this will not work. You will need that pass phrase added here in order to remove it in the next step.

openssl pkcs12 -legacy -nocerts -out key.pem -in key.p12

Remove the PEM pass phrase from the key.

openssl rsa -in key.pem -out key_unencrypted.pem

cert.pem and key_unencrypted.pem can now be used in your configuration.