Pigeon.APNS.Notification (Pigeon v2.1.0)

@type error_response() ::
  :bad_certificate
  | :bad_certificate_environment
  | :bad_collapse_id
  | :bad_device_token
  | :bad_environment_key_id_in_token
  | :bad_expiration_date
  | :bad_message_id
  | :bad_path
  | :bad_priority
  | :bad_topic
  | :device_token_not_for_topic
  | :duplicate_headers
  | :expired_provider_token
  | :expired_token
  | :forbidden
  | :idle_timeout
  | :internal_server_error
  | :invalid_provider_token
  | :invalid_push_type
  | :method_not_allowed
  | :missing_device_token
  | :missing_provider_token
  | :missing_topic
  | :payload_empty
  | :payload_too_large
  | :service_unavailable
  | :shutdown
  | :too_many_provider_token_updates
  | :too_many_requests
  | :topic_disallowed
  | :unknown_error
  | :unregistered
  | :unrelated_key_id_in_token

APNS error response

Each atom is the snake_case form of the reason in the APNS response body. See Handling notification responses from APNs for the meaning of each one. :unknown_error covers any reason Pigeon does not recognize.

response()

@type response() ::
  error_response() | nil | :not_connected | :not_started | :success | :timeout

APNS push response

Pigeon.APNS.Notification.error_response/0 - Push attempted but server responded with error.
nil - Push has not been sent yet.
:not_connected - Dispatcher had no live connection to APNS. Push was not sent.
:not_started - Dispatcher is not running. Push was not sent.
:success - Push was successfully sent.
:timeout - Push was sent but the connection dropped before APNS responded. Delivery is unknown.

t()

@type t() :: %Pigeon.APNS.Notification{
  __meta__: Pigeon.Metadata.t(),
  collapse_id: String.t() | nil,
  device_token: String.t() | nil,
  expiration: non_neg_integer() | nil,
  id: String.t() | nil,
  payload: %{required(String.t()) => term()},
  priority: non_neg_integer() | nil,
  push_type: String.t() | nil,
  response: response(),
  topic: String.t() | nil
}

APNS notification

Examples

%Pigeon.APNS.Notification{
    __meta__: %Pigeon.Metadata{on_response: nil},
    collapse_id: nil,
    device_token: "device token",
    expiration: nil,
    id: nil, # Set on push response if nil
    payload: %{"aps" => %{"alert" => "push message"}},
    priority: nil,
    push_type: "alert",
    response: nil, # Set on push response
    topic: "com.example.YourApp"
}

Functions

new(msg, token, topic \\ nil)

@spec new(String.t() | map(), String.t(), String.t() | nil) :: t()

Returns an APNS.Notification struct with given message, device token, and topic (optional).

Push payload is constructed in the form of %{"aps" => %{"alert" => msg}}

Examples

iex> Pigeon.APNS.Notification.new("push message", "device token")
%Pigeon.APNS.Notification{
  __meta__: %Pigeon.Metadata{},
  device_token: "device token",
  expiration: nil,
  priority: nil,
  push_type: "alert",
  id: nil,
  payload: %{"aps" => %{"alert" => "push message"}},
  topic: nil
}

new(msg, token, topic, id)

@spec new(String.t() | map(), String.t(), String.t(), String.t()) :: t()

Returns an APNS.Notification struct with given message, device token, topic, and message ID.

Push payload is constructed in the form of %{"aps" => %{"alert" => msg}}

Examples

iex> Pigeon.APNS.Notification.new("push message", "device token", "topic", "id_1234")
%Pigeon.APNS.Notification{
  collapse_id: nil,
  device_token: "device token",
  expiration: nil,
  priority: nil,
  push_type: "alert",
  id: "id_1234",
  payload: %{"aps" => %{"alert" => "push message"}},
  topic: "topic"
}

put_alert(notification, alert)

@spec put_alert(t(), String.t() | map()) :: t()

Updates "alert" key in push payload.

This is the alert message displayed on the device.

Examples

iex> Pigeon.APNS.Notification.put_alert(%Pigeon.APNS.Notification{}, "push message")
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"alert" => "push message"}}
}

put_badge(notification, badge)

@spec put_badge(t(), integer()) :: t()

Updates "badge" key in push payload.

This is the badge number displayed on the application.

Examples

iex> Pigeon.APNS.Notification.put_badge(%Pigeon.APNS.Notification{}, 5)
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"badge" => 5}}
}

put_category(notification, category)

@spec put_category(t(), String.t()) :: t()

Updates "category" key in push payload.

Examples

iex> Pigeon.APNS.Notification.put_category(%Pigeon.APNS.Notification{}, "category")
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"category" => "category"}}
}

put_content_available(notification)

@spec put_content_available(t()) :: t()

Sets "content-available" flag in push payload.

Used for silent notifications. When set, ensure alert, badge, and sound keys are not configured.

Examples

iex> Pigeon.APNS.Notification.put_content_available(%Pigeon.APNS.Notification{})
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"content-available" => 1}}
}

put_custom(notification, data)

@spec put_custom(t(), %{required(String.t()) => term()}) :: t()

Puts custom data in push payload.

Examples

iex> n = Pigeon.APNS.Notification.new("test message", "device token")
iex> Pigeon.APNS.Notification.put_custom(n, %{"custom-key" => 1234})
%Pigeon.APNS.Notification{
  device_token: "device token",
  payload: %{"aps" => %{"alert" => "test message"}, "custom-key" => 1234}
}

put_interruption_level(notification, level)

@spec put_interruption_level(t(), String.t()) :: t()

Updates "interruption-level" key in push payload.

Used for managing time sensitive notifications

Examples

iex> Pigeon.APNS.Notification.put_interruption_level(%Pigeon.APNS.Notification{}, "time-sensitive")
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"interruption-level" => "time-sensitive"}}
}

put_mutable_content(notification)

@spec put_mutable_content(t()) :: t()

Sets "mutable-content" flag in push payload.

Used for notification service extensions (such as displaying custom media).

Examples

iex> Pigeon.APNS.Notification.put_mutable_content(%Pigeon.APNS.Notification{})
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"mutable-content" => 1}}
}

put_sound(notification, sound)

@spec put_sound(t(), String.t() | %{required(String.t()) => term()}) :: t()

Updates "sound" key in push payload.

Used for custom notification sounds. Value should be the name of the custom sound file in the application's binary.

Examples

iex> Pigeon.APNS.Notification.put_sound(%Pigeon.APNS.Notification{}, "custom.aiff")
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"sound" => "custom.aiff"}}
}

iex> Pigeon.APNS.Notification.put_sound(%Pigeon.APNS.Notification{}, %{
...>   "critical" => 1,
...>   "sound" => "default",
...>   "volume" => 1.0
...> })
%Pigeon.APNS.Notification{
  payload: %{
    "aps" => %{
      "sound" => %{
        "critical" => 1,
        "sound" => "default",
        "volume" => 1.0
      }
    }
  }
}

put_target_content_id(notification, id)

@spec put_target_content_id(t(), String.t()) :: t()

Updates "target-content-id" key in push payload.

Used for bringing a specific window forward.

Examples

iex> Pigeon.APNS.Notification.put_target_content_id(%Pigeon.APNS.Notification{}, "example")
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"target-content-id" => "example"}}
}

put_thread_id(notification, id)

@spec put_thread_id(t(), String.t()) :: t()

Updates "thread-id" key in push payload.

Used for grouping related notifications.

Examples

iex> Pigeon.APNS.Notification.put_thread_id(%Pigeon.APNS.Notification{}, "example")
%Pigeon.APNS.Notification{
  payload: %{"aps" => %{"thread-id" => "example"}}
}