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

Defines Pigeon.LegacyFCM.Notification struct and convenience constructor functions.

Link to this section Summary

Types

LegacyFCM push response for individual registration IDs

Status of LegacyFCM request

t()

Functions

Creates LegacyFCM.Notification struct with device registration IDs and optional notification and data payloads.

Updates "collapse_key" key.

Updates "condition" key.

Updates "content_available" key.

Updates "data" key in push payload.

Sets "dry_run" key to true.

Updates "mutable_content" key.

Updates "notification" key in push payload.

Updates "priority" key.

Updates "restricted_package_name" key.

Updates "time_to_live" key.

Returns a list of registration IDs that should be removed

Returns a list of registration IDs that should be retried

Returns a list of successful registration IDs

Returns a list of registration IDs and their corresponding new ID

Link to this section Types

Link to this type

regid_error_response()

View Source

Specs

regid_error_response() ::
  :device_message_rate_exceeded
  | :internal_server_error
  | :invalid_apns_credential
  | :invalid_data_key
  | :invalid_package_name
  | :invalid_parameters
  | :invalid_registration
  | :invalid_ttl
  | :message_too_big
  | :missing_registration
  | :mismatch_sender_id
  | :not_registered
  | :topics_message_rate_exceeded
  | :unavailable
  | :unknown_error

Specs

regid_response() ::
  {:success, binary()}
  | {regid_error_response(), binary()}
  | {:update, {binary(), binary()}}

LegacyFCM push response for individual registration IDs

  • {:success, "reg_id"} - Push was successfully sent
  • {:update, {"reg_id", "new_reg_id"}} - Push successful but user should use new registration ID for future pushes
  • {regid_error_response, "reg_id"} - Push attempted but server responded with error

Specs

status() ::
  :success
  | :timeout
  | :unauthorized
  | :malformed_json
  | :internal_server_error
  | :unavailable

Status of LegacyFCM request

  • :success - Notification was processed successfully
  • :timeout - Worker did not respond within timeout. This is likely an internal error
  • :unauthorized - Bad LegacyFCM key
  • :malformed_json - Push payload was invalid JSON
  • :internal_server_error - LegacyFCM server encountered an error while trying to process the request
  • :unavailable - LegacyFCM server couldn't process the request in time

Specs

t() :: %Pigeon.LegacyFCM.Notification{
  __meta__: Pigeon.Metadata.t(),
  collapse_key: nil | String.t(),
  condition: nil | String.t(),
  content_available: boolean(),
  dry_run: boolean(),
  message_id: nil | String.t(),
  mutable_content: boolean(),
  payload: map(),
  priority: :normal | :high,
  registration_id: String.t() | [String.t()],
  response: [] | [regid_response(), ...],
  restricted_package_name: nil | String.t(),
  status: status() | nil,
  time_to_live: non_neg_integer()
}

Link to this section Functions

Link to this function

new(registration_ids, notification \\ %{}, data \\ %{})

View Source

Creates LegacyFCM.Notification struct with device registration IDs and optional notification and data payloads.

Examples

iex> Pigeon.LegacyFCM.Notification.new("reg ID")
%Pigeon.LegacyFCM.Notification{
  payload: %{},
  registration_id: "reg ID",
  priority: :normal
}

iex> Pigeon.LegacyFCM.Notification.new("reg ID", %{"body" => "test message"})
%Pigeon.LegacyFCM.Notification{
  payload: %{"notification" => %{"body" => "test message"}},
  registration_id: "reg ID",
  priority: :normal
}

iex> Pigeon.LegacyFCM.Notification.new("reg ID", %{"body" => "test message"},
...> %{"key" => "value"})
%Pigeon.LegacyFCM.Notification{
  payload: %{
    "data" => %{"key" => "value"},
    "notification" => %{"body" => "test message"}
  },
  registration_id: "reg ID",
  priority: :normal
}

iex> regids = Enum.map(0..1_499, fn(_x) -> "reg ID" end)
iex> [n1 | [n2]] = Pigeon.LegacyFCM.Notification.new(regids,
...> %{"body" => "test message"}, %{"key" => "value"})
iex> Enum.count(n1.registration_id)
1000
iex> Enum.count(n2.registration_id)
500
Link to this function

put_collapse_key(n, key)

View Source

Updates "collapse_key" key.

Examples

iex> put_collapse_key(%Pigeon.LegacyFCM.Notification{}, "Updates available")
%Pigeon.LegacyFCM.Notification{collapse_key: "Updates available"}
Link to this function

put_condition(n, condition)

View Source

Updates "condition" key.

Supported condition: Topic, formatted as "'yourTopic' in topics". This value is case-insensitive.

Supported operators: &&, ||. Maximum two operators per topic message supported.

Examples

iex> put_condition(%Pigeon.LegacyFCM.Notification{}, "'test' in topics")
%Pigeon.LegacyFCM.Notification{condition: "'test' in topics"}
Link to this function

put_content_available(n, enabled)

View Source

Updates "content_available" key.

On iOS, use this field to represent content-available in the APNs payload. When a notification or message is sent and this is set to true, an inactive client app is awoken, and the message is sent through APNs as a silent notification and not through the FCM connection server. Note that silent notifications in APNs are not guaranteed to be delivered, and can depend on factors such as the user turning on Low Power Mode, force quitting the app, etc. On Android, data messages wake the app by default. On Chrome, currently not supported.

Examples

iex> put_content_available(%Pigeon.LegacyFCM.Notification{}, true)
%Pigeon.LegacyFCM.Notification{content_available: true}

Updates "data" key in push payload.

This parameter specifies the custom key-value pairs of the message's payload.

For example, with data:{"score":"3x1"}:

On iOS, if the message is sent via APNs, it represents the custom data fields. If it is sent via FCM connection server, it would be represented as key value dictionary in AppDelegate application:didReceiveRemoteNotification:.

On Android, this would result in an intent extra named score with the string value 3x1.

The key should not be a reserved word ("from" or any word starting with "google" or "gcm"). Do not use any of the words defined in this table (such as collapse_key).

Values in string types are recommended. You have to convert values in objects or other non-string data types (e.g., integers or booleans) to string.

Examples

iex> put_data(%Pigeon.LegacyFCM.Notification{}, %{"key" => 1234})
%Pigeon.LegacyFCM.Notification{
  payload: %{"data" => %{"key" => 1234}},
  registration_id: nil
}

Sets "dry_run" key to true.

This parameter, when set to true, allows developers to test a request without actually sending a message.

The default value is false.

Examples

iex> put_dry_run(%Pigeon.LegacyFCM.Notification{})
%Pigeon.LegacyFCM.Notification{dry_run: true}
Link to this function

put_mutable_content(n, enabled)

View Source

Updates "mutable_content" key.

Currently for iOS 10+ devices only. On iOS, use this field to represent mutable-content in the APNs payload. When a notification is sent and this is set to true, the content of the notification can be modified before it is displayed, using a Notification Service app extension. This parameter will be ignored for Android and web.

Examples

iex> put_mutable_content(%Pigeon.LegacyFCM.Notification{}, true)
%Pigeon.LegacyFCM.Notification{mutable_content: true}
Link to this function

put_notification(n, notification)

View Source

Updates "notification" key in push payload.

This parameter specifies the predefined, user-visible key-value pairs of the notification payload. See Notification payload support for detail. For more information about notification message and data message options, see Message types. If a notification payload is provided, or the content_available option is set to true for a message to an iOS device, the message is sent through APNs, otherwise it is sent through the FCM connection server.

Examples

iex> put_notification(%Pigeon.LegacyFCM.Notification{},
...> %{"body" => "message"})
%Pigeon.LegacyFCM.Notification{
  payload: %{"notification" => %{"body" => "message"}},
  registration_id: nil
}

Updates "priority" key.

Sets the priority of the message. Valid values are "normal" and "high." On iOS, these correspond to APNs priorities 5 and 10.

By default, notification messages are sent with high priority, and data messages are sent with normal priority. Normal priority optimizes the client app's battery consumption and should be used unless immediate delivery is required. For messages with normal priority, the app may receive the message with unspecified delay.

When a message is sent with high priority, it is sent immediately, and the app can display a notification.

Examples

iex> put_priority(%Pigeon.LegacyFCM.Notification{}, :normal)
%Pigeon.LegacyFCM.Notification{priority: :normal}

iex> put_priority(%Pigeon.LegacyFCM.Notification{}, :high)
%Pigeon.LegacyFCM.Notification{priority: :high}

iex> put_priority(%Pigeon.LegacyFCM.Notification{priority: :normal}, :bad)
%Pigeon.LegacyFCM.Notification{priority: :normal}
Link to this function

put_restricted_package_name(n, name)

View Source

Updates "restricted_package_name" key.

This parameter specifies the package name of the application where the registration tokens must match in order to receive the message. (Only affects android)

Examples

iex> put_restricted_package_name(%Pigeon.LegacyFCM.Notification{}, "com.example.app")
%Pigeon.LegacyFCM.Notification{restricted_package_name: "com.example.app"}
Link to this function

put_time_to_live(n, ttl)

View Source

Updates "time_to_live" key.

This parameter specifies how long (in seconds) the message should be kept in FCM storage if the device is offline. The maximum time to live supported is 4 weeks, and the default value is 4 weeks. For more information, see Setting the lifespan of a message.

Examples

iex> put_time_to_live(%Pigeon.LegacyFCM.Notification{}, 60 * 60 * 24)
%Pigeon.LegacyFCM.Notification{time_to_live: 86_400}

Returns a list of registration IDs that should be removed

Examples

iex> n = %Pigeon.LegacyFCM.Notification{response: [
...> {:success, "regid1"}, {:invalid_registration, "regid2"},
...> {:success, "regid3"}, {:update, {"regid4", "new_regid4"}},
...> {:not_registered, "regid5"}, {:unavailable, "regid6"}]}
iex> remove?(n)
["regid2", "regid5"]

Returns a list of registration IDs that should be retried

Examples

iex> n = %Pigeon.LegacyFCM.Notification{response: [
...> {:success, "regid1"}, {:invalid_registration, "regid2"},
...> {:success, "regid3"}, {:update, {"regid4", "new_regid4"}},
...> {:not_registered, "regid5"}, {:unavailable, "regid6"}]}
iex> retry?(n)
["regid6"]

Returns a list of successful registration IDs

Examples

iex> n = %Pigeon.LegacyFCM.Notification{response: [
...> {:success, "regid1"}, {:invalid_registration, "regid2"},
...> {:success, "regid3"}, {:update, {"regid4", "new_regid4"}},
...> {:not_registered, "regid5"}, {:unavailable, "regid6"}]}
iex> success?(n)
["regid1", "regid3"]

Returns a list of registration IDs and their corresponding new ID

Examples

iex> n = %Pigeon.LegacyFCM.Notification{response: [
...> {:success, "regid1"}, {:invalid_registration, "regid2"},
...> {:success, "regid3"}, {:update, {"regid4", "new_regid4"}},
...> {:not_registered, "regid5"}, {:unavailable, "regid6"}]}
iex> update?(n)
[{"regid4", "new_regid4"}]