FCM (Android)

Usage

  1. Set your environment variables.

    config :pigeon, :fcm,
      fcm_default: %{
        key: "your_fcm_key_here"
      }
  2. Create a notification packet.

    msg = %{ "body" => "your message" }
    n = Pigeon.FCM.Notification.new("your device registration ID", msg)
  3. Send the packet.

    Pigeon.FCM.push(n)

Sending to Multiple Registration IDs

Pass in a list of registration IDs, as many as you want.

  msg = %{ "body" => "your message" }
  n = Pigeon.FCM.Notification.new(["first ID", "second ID"], msg)

Notification Struct

  %Pigeon.FCM.Notification{
      payload: %{...},
      registration_id: String.t | [String.t],
      priority: :normal | :high
  }

Notifications with Custom Data

FCM accepts both notification and data keys in its JSON payload. Set them like so:

  notification = %{ "body" => "your message" }
  data = %{ "key" => "value" }
  Pigeon.FCM.Notification.new("registration ID", notification, data)

or

  Pigeon.FCM.Notification.new("registration ID")
  |> put_notification(%{ "body" => "your message" })
  |> put_data(%{ "key" => "value" })

Handling Push Responses

  1. Pass an optional anonymous function as your second parameter.

    data = %{ message: "your message" }
    n = Pigeon.FCM.Notification.new(data, "device registration ID")
    Pigeon.FCM.push(n, fn(x) -> IO.inspect(x) end)
    {:ok, %Pigeon.FCM.NotificationResponse{...}}
  2. Reponses return a tuple of either {:ok, notification_response} or {:error, reason, notification}. You could handle responses like so:

    on_response = fn(x) ->
      case x do
        {:ok, notification_response} ->
          # Handle updated registration ID's, etc.
        {:error, :timeout, notification} ->
          # Maybe bad connection or the port is blocked?
      end
    end
    
    data = %{ message: "your message" }
    n = Pigeon.FCM.Notification.new(data, "your device token")
    Pigeon.FCM.push(n, on_response)

NotificationResponse Struct

Registration IDs are conveniently grouped based on their response. :error is a map of all other miscellaneous errors, with their corresponding registration IDs.

  %Pigeon.FCM.NotificationResponse{
      message_id: nil,
      ok: ["reg_id", ...],
      update: [{"old_reg_id", "new_reg_id"}, ...],
      retry: ["reg_id", ...],
      remove: ["reg_id", ...],
      error: %{atom => ["reg_id", ...]}
  }

Error Responses

Slightly modified from FCM Server Reference

ReasonDescription
:missing_registrationMissing Registration Token
:invalid_registrationInvalid Registration Token
:not_registeredUnregistered Device
:invalid_package_nameInvalid Package Name
:authentication_errorAuthentication Error
:mismatch_sender_idMismatched Sender
:invalid_jsonInvalid JSON
:message_too_bigMessage Too Big
:invalid_data_keyInvalid Data Key
:invalid_ttlInvalid Time to Live
:unavailableTimeout
:internal_server_errorInternal Server Error
:device_message_rate_exceededMessage Rate Exceeded
:topics_message_rate_exceededTopics Message Rate Exceeded
:unknown_errorUnknown Error