messaging

Documentation

Overview

Package messaging contains functions for sending messages and managing device subscriptions with Firebase Cloud Messaging (FCM).

Index

• type APNSConfig
• type APNSPayload
  • func (p *APNSPayload) MarshalJSON() ([]byte, error)
• type AndroidConfig
  • func (a *AndroidConfig) MarshalJSON() ([]byte, error)
• type AndroidNotification
• type Aps
  • func (a *Aps) MarshalJSON() ([]byte, error)
• type ApsAlert
• type Client
  • func NewClient(ctx context.Context, c *internal.MessagingConfig) (*Client, error)
  • func (c *Client) Send(ctx context.Context, message *Message) (string, error)
  • func (c *Client) SendDryRun(ctx context.Context, message *Message) (string, error)
  • func (c *Client) SubscribeToTopic(ctx context.Context, tokens []string, topic string) (*TopicManagementResponse, error)
  • func (c *Client) UnsubscribeFromTopic(ctx context.Context, tokens []string, topic string) (*TopicManagementResponse, error)
• type ErrorInfo
• type Message
  • func (m *Message) MarshalJSON() ([]byte, error)
• type Notification
• type TopicManagementResponse
• type WebpushConfig
• type WebpushNotification

Types

type APNSConfig

type APNSConfig struct {
	Headers map[string]string `json:"headers,omitempty"`
	Payload *APNSPayload      `json:"payload,omitempty"`
}

APNSConfig contains messaging options specific to the Apple Push Notification Service (APNS).

See https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html for more details on supported headers and payload keys.

type APNSPayload

type APNSPayload struct {
	Aps        *Aps
	CustomData map[string]interface{}
}

APNSPayload is the payload that can be included in an APNS message.

The payload mainly consists of the aps dictionary. Additionally it may contain arbitrary key-values pairs as custom data fields.

See https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html for a full list of supported payload fields.

func (*APNSPayload) MarshalJSON

func (p *APNSPayload) MarshalJSON() ([]byte, error)

MarshalJSON marshals an APNSPayload into JSON (for internal use only).

type AndroidConfig

type AndroidConfig struct {
	CollapseKey           string               `json:"collapse_key,omitempty"`
	Priority              string               `json:"priority,omitempty"` // one of "normal" or "high"
	TTL                   *time.Duration       `json:"-"`
	RestrictedPackageName string               `json:"restricted_package_name,omitempty"`
	Data                  map[string]string    `json:"data,omitempty"` // if specified, overrides the Data field on Message type
	Notification          *AndroidNotification `json:"notification,omitempty"`
}

AndroidConfig contains messaging options specific to the Android platform.

func (*AndroidConfig) MarshalJSON

func (a *AndroidConfig) MarshalJSON() ([]byte, error)

MarshalJSON marshals an AndroidConfig into JSON (for internal use only).

type AndroidNotification

type AndroidNotification struct {
	Title        string   `json:"title,omitempty"` // if specified, overrides the Title field of the Notification type
	Body         string   `json:"body,omitempty"`  // if specified, overrides the Body field of the Notification type
	Icon         string   `json:"icon,omitempty"`
	Color        string   `json:"color,omitempty"` // notification color in #RRGGBB format
	Sound        string   `json:"sound,omitempty"`
	Tag          string   `json:"tag,omitempty"`
	ClickAction  string   `json:"click_action,omitempty"`
	BodyLocKey   string   `json:"body_loc_key,omitempty"`
	BodyLocArgs  []string `json:"body_loc_args,omitempty"`
	TitleLocKey  string   `json:"title_loc_key,omitempty"`
	TitleLocArgs []string `json:"title_loc_args,omitempty"`
}

AndroidNotification is a notification to send to Android devices.

type Aps

type Aps struct {
	AlertString      string    `json:"-"`
	Alert            *ApsAlert `json:"-"`
	Badge            *int      `json:"badge,omitempty"`
	Sound            string    `json:"sound,omitempty"`
	ContentAvailable bool      `json:"-"`
	Category         string    `json:"category,omitempty"`
	ThreadID         string    `json:"thread-id,omitempty"`
}

Aps represents the aps dictionary that may be included in an APNSPayload.

Alert may be specified as a string (via the AlertString field), or as a struct (via the Alert field).

func (*Aps) MarshalJSON

func (a *Aps) MarshalJSON() ([]byte, error)

MarshalJSON marshals an Aps into JSON (for internal use only).

type ApsAlert

type ApsAlert struct {
	Title        string   `json:"title,omitempty"` // if specified, overrides the Title field of the Notification type
	Body         string   `json:"body,omitempty"`  // if specified, overrides the Body field of the Notification type
	LocKey       string   `json:"loc-key,omitempty"`
	LocArgs      []string `json:"loc-args,omitempty"`
	TitleLocKey  string   `json:"title-loc-key,omitempty"`
	TitleLocArgs []string `json:"title-loc-args,omitempty"`
	ActionLocKey string   `json:"action-loc-key,omitempty"`
	LaunchImage  string   `json:"launch-image,omitempty"`
}

ApsAlert is the alert payload that can be included in an Aps.

See https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html for supported fields.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the interface for the Firebase Cloud Messaging (FCM) service.

func NewClient

func NewClient(ctx context.Context, c *internal.MessagingConfig) (*Client, error)

NewClient creates a new instance of the Firebase Cloud Messaging Client.

This function can only be invoked from within the SDK. Client applications should access the the messaging service through firebase.App.

func (*Client) Send

func (c *Client) Send(ctx context.Context, message *Message) (string, error)

Send sends a Message to Firebase Cloud Messaging.

The Message must specify exactly one of Token, Topic and Condition fields. FCM will customize the message for each target platform based on the arguments specified in the Message.

func (*Client) SendDryRun

func (c *Client) SendDryRun(ctx context.Context, message *Message) (string, error)

SendDryRun sends a Message to Firebase Cloud Messaging in the dry run (validation only) mode.

This function does not actually deliver the message to target devices. Instead, it performs all the SDK-level and backend validations on the message, and emulates the send operation.

func (*Client) SubscribeToTopic

func (c *Client) SubscribeToTopic(ctx context.Context, tokens []string, topic string) (*TopicManagementResponse, error)

SubscribeToTopic subscribes a list of registration tokens to a topic.

The tokens list must not be empty, and have at most 1000 tokens.

func (*Client) UnsubscribeFromTopic

func (c *Client) UnsubscribeFromTopic(ctx context.Context, tokens []string, topic string) (*TopicManagementResponse, error)

UnsubscribeFromTopic unsubscribes a list of registration tokens from a topic.

The tokens list must not be empty, and have at most 1000 tokens.

type ErrorInfo

type ErrorInfo struct {
	Index  int
	Reason string
}

ErrorInfo is a topic management error.

type Message

type Message struct {
	Data         map[string]string `json:"data,omitempty"`
	Notification *Notification     `json:"notification,omitempty"`
	Android      *AndroidConfig    `json:"android,omitempty"`
	Webpush      *WebpushConfig    `json:"webpush,omitempty"`
	APNS         *APNSConfig       `json:"apns,omitempty"`
	Token        string            `json:"token,omitempty"`
	Topic        string            `json:"-"`
	Condition    string            `json:"condition,omitempty"`
}

Message to be sent via Firebase Cloud Messaging.

Message contains payload data, recipient information and platform-specific configuration options. A Message must specify exactly one of Token, Topic or Condition fields. Apart from that a Message may specify any combination of Data, Notification, Android, Webpush and APNS fields. See https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages for more details on how the backend FCM servers handle different message parameters.

func (*Message) MarshalJSON

func (m *Message) MarshalJSON() ([]byte, error)

MarshalJSON marshals a Message into JSON (for internal use only).

type Notification

type Notification struct {
	Title string `json:"title,omitempty"`
	Body  string `json:"body,omitempty"`
}

Notification is the basic notification template to use across all platforms.

type TopicManagementResponse

type TopicManagementResponse struct {
	SuccessCount int
	FailureCount int
	Errors       []*ErrorInfo
}

TopicManagementResponse is the result produced by topic management operations.

TopicManagementResponse provides an overview of how many input tokens were successfully handled, and how many failed. In case of failures, the Errors list provides specific details concerning each error.

type WebpushConfig

type WebpushConfig struct {
	Headers      map[string]string    `json:"headers,omitempty"`
	Data         map[string]string    `json:"data,omitempty"`
	Notification *WebpushNotification `json:"notification,omitempty"`
}

WebpushConfig contains messaging options specific to the WebPush protocol.

See https://tools.ietf.org/html/rfc8030#section-5 for additional details, and supported headers.

type WebpushNotification

type WebpushNotification struct {
	Title string `json:"title,omitempty"` // if specified, overrides the Title field of the Notification type
	Body  string `json:"body,omitempty"`  // if specified, overrides the Body field of the Notification type
	Icon  string `json:"icon,omitempty"`
}

WebpushNotification is a notification to send via WebPush protocol.