README

Firebase Cloud Notifications Client

Go Report Card Build StatusMIT Licence Coverage Status

Firebase Cloud Messaging for application servers implemented using the Go programming language. It's designed for simple push notification sending via HTTP API

Getting started

To install fcm, use go get:

go get gopkg.in/maddevsio/fcm.v1

Import fcm with the following:

import "gopkg.in/maddevsio/fcm.v1"

Sample usage

package main

import (
	"fmt"
	"log"

	"gopkg.in/maddevsio/fcm.v1"
)

func main() {
	data := map[string]string{
		"msg": "Hello World1",
		"sum": "Happy Day",
	}
	c := fcm.NewFCM("serverKey")
	token := "token"
	response, err := c.Send(fcm.Message{
		Data:             data,
		RegistrationIDs:  []string{token},
		ContentAvailable: true,
		Priority:         fcm.PriorityHigh,
		Notification: fcm.Notification{
			Title: "Hello",
			Body:  "World",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Status Code   :", response.StatusCode)
	fmt.Println("Success       :", response.Success)
	fmt.Println("Fail          :", response.Fail)
	fmt.Println("Canonical_ids :", response.CanonicalIDs)
	fmt.Println("Topic MsgId   :", response.MsgID)
}

More examples can be found in /_examples/ directory

License

MIT License

Copyright (c) 2017 Mad Devs Developers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Expand ▾ Collapse ▴

Documentation

Overview

    Package firebase provides integration with Firebase Cloud Notification HTTP API https://firebase.google.com/docs/cloud-messaging/http-server-ref You can send push notifications to Android and iOS devices via simple API.

    Example:

    package main
    
    import (
    	"fmt"
    	"log"
    
    	"github.com/maddevsio/fcm"
    )
    
    func main() {
    	data := map[string]string{
    		"msg": "Hello World1",
    		"sum": "Happy Day",
    	}
    	c := fcm.NewFCM("serverKey")
    	token := "token"
    	response, err := c.Send(&fcm.Message{
    		Data:             data,
    		RegistrationIDs:  []string{token},
    		ContentAvailable: true,
    		Priority:         fcm.PriorityHigh,
    		Notification: &fcm.Notification{
    			Title: "Hello",
    			Body:  "World",
    		},
    	})
    	if err != nil {
    		log.Fatal(err)
    	}
    	fmt.Println("Status Code   :", response.StatusCode)
    	fmt.Println("Success       :", response.Success)
    	fmt.Println("Fail          :", response.Fail)
    	fmt.Println("Canonical_ids :", response.CanonicalIDs)
    	fmt.Println("Topic MsgId   :", response.MsgID)
    }
    

    If you want to send notification with Sound or Badge, then use:

    response, err := c.Send(&fcm.Message{
    	Notification: &fcm.Notification{
    		Title: "Hello",
    		Body:  "World",
    		Sound: "default",
    		Badge: "3",
    	},
    })
    

    Index

    Constants

    View Source
    const (
    	// PriorityHigh used for high notification priority
    	PriorityHigh = "high"
    
    	// PriorityNormal used for normal notification priority
    	PriorityNormal = "normal"
    
    	// HeaderRetryAfter HTTP header constant
    	HeaderRetryAfter = "Retry-After"
    
    	// ErrorKey readable error caching
    	ErrorKey = "error"
    
    	// MethodPOST indicates http post method
    	MethodPOST = "POST"
    )

    Variables

    View Source
    var (
    
    	// fcmServerUrl for testing purposes
    	FCMServerURL = "https://fcm.googleapis.com/fcm/send"
    )

    Functions

    This section is empty.

    Types

    type FCM

    type FCM struct {
    	APIKey     string
    	HttpClient *http.Client
    }

      FCM stores client with api key to firebase

      func NewFCM

      func NewFCM(apiKey string) *FCM

        NewFCM creates a new client

        func NewFCMWithClient

        func NewFCMWithClient(apiKey string, httpClient *http.Client) *FCM

          NewFCM creates a new client

          func (*FCM) AuthorizationToken

          func (f *FCM) AuthorizationToken() string

          func (*FCM) Failed

          func (f *FCM) Failed(response *Response) error

            Failed method indicates if the server couldn't process the request in time.

            func (*FCM) Send

            func (f *FCM) Send(message Message) (Response, error)

              Send message to FCM

              type Message

              type Message struct {
              	// Data 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.
              	//
              	Data interface{} `json:"data,omitempty"`
              
              	// To this parameter specifies the recipient of a message.
              	//
              	// The value must be a registration token, notification key, or topic.
              	// Do not set this field when sending to multiple topics. See Condition.
              	To string `json:"to,omitempty"`
              
              	// RegistrationIDs for all registration ids
              	// This parameter specifies a list of devices
              	// (registration tokens, or IDs) receiving a multicast message.
              	// It must contain at least 1 and at most 1000 registration tokens.
              	// Use this parameter only for multicast messaging, not for single recipients.
              	// Multicast messages (sending to more than 1 registration tokens)
              	// are allowed using HTTP JSON format only.
              	RegistrationIDs []string `json:"registration_ids,omitempty"`
              
              	// CollapseKey This parameter identifies a group of messages
              	// (e.g., with collapse_key: "Updates Available") that can be collapsed,
              	// so that only the last message gets sent when delivery can be resumed.
              	// This is intended to avoid sending too many of the same messages when the
              	// device comes back online or becomes active (see delay_while_idle).
              	CollapseKey string `json:"collapse_key,omitempty"`
              
              	// Priority 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 wake a sleeping device and open a network connection to your server.
              	// For more information, see Setting the priority of a message.
              	Priority string `json:"priority,omitempty"`
              
              	// Notification 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
              	// Notification
              	Notification Notification `json:"notification,omitempty"`
              
              	// ContentAvailable 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. On Android, data messages wake
              	// the app by default. On Chrome, currently not supported.
              	ContentAvailable bool `json:"content_available,omitempty"`
              
              	// DelayWhenIdle When this parameter is set to true, it indicates that
              	// the message should not be sent until the device becomes active.
              	// The default value is false.
              	DelayWhileIdle bool `json:"delay_while_idle,omitempty"`
              
              	// TimeToLive 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
              	// https://firebase.google.com/docs/cloud-messaging/concept-options#ttl
              	TimeToLive int `json:"time_to_live,omitempty"`
              
              	// RestrictedPackageName This parameter specifies the package name of the
              	// application where the registration tokens must match in order to
              	// receive the message.
              	RestrictedPackageName string `json:"restricted_package_name,omitempty"`
              
              	// DryRun This parameter, when set to true, allows developers to test
              	// a request without actually sending a message.
              	// The default value is false
              	DryRun bool `json:"dry_run,omitempty"`
              
              	// Condition to set a logical expression of conditions that determine the message target
              	// This parameter specifies a logical expression of conditions that determine the message target.
              	// Supported condition: Topic, formatted as "'yourTopic' in topics". This value is case-insensitive.
              	// Supported operators: &&, ||. Maximum two operators per topic message supported.
              	Condition string `json:"condition,omitempty"`
              
              	// 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.
              	MutableContent bool `json:"mutable_content,omitempty"`
              }

                Message represents fcm request message

                type Notification

                type Notification struct {
                	// Title indicates notification title. This field is not visible on iOS phones and tablets.
                	Title string `json:"title,omitempty"`
                
                	// Body indicates notification body text.
                	Body string `json:"body,omitempty"`
                
                	// Image should contains the URL of an image that is going to be downloaded on the device and displayed in a notification.
                	Image string `json:"image,omitempty"`
                
                	// AndroidChannelID The notification's channel id (new in Android O).
                	// The app must create a channel with this channel ID before any notification with this channel ID is received.
                	// If you don't send this channel ID in the request, or if the channel ID provided has
                	// not yet been created by the app, FCM uses the channel ID specified in the app manifest.
                	AndroidChannelID string `json:"android_channel_id,omitempty"`
                
                	// Sound indicates a sound to play when the device receives a notification.
                	// Sound files can be in the main bundle of the client app or in the
                	// Library/Sounds folder of the app's data container.
                	// See the iOS Developer Library for more information.
                	// http://apple.co/2jaGqiE
                	Sound string `json:"sound,omitempty"`
                
                	// Badge indicates the badge on the client app home icon.
                	Badge string `json:"badge,omitempty"`
                
                	// Icon indicates notification icon. Sets value to myicon for drawable resource myicon.
                	// If you don't send this key in the request, FCM displays the launcher icon specified
                	// in your app manifest.
                	Icon string `json:"icon,omitempty"`
                
                	// Tag indicates whether each notification results in a new entry in the notification
                	// drawer on Android. If not set, each request creates a new notification.
                	// If set, and a notification with the same tag is already being shown,
                	// the new notification replaces the existing one in the notification drawer.
                	Tag string `json:"tag,omitempty"`
                
                	// Color indicates color of the icon, expressed in #rrggbb format
                	Color string `json:"color,omitempty"`
                
                	// ClickAction indicates the action associated with a user click on the notification.
                	// When this is set, an activity with a matching intent filter is launched when user
                	// clicks the notification.
                	ClickAction string `json:"click_action,omitempty"`
                
                	// BodyLockKey indicates the key to the body string for localization. Use the key in
                	// the app's string resources when populating this value.
                	BodyLocKey string `json:"body_loc_key,omitempty"`
                
                	// BodyLocArgs indicates the string value to replace format specifiers in the body
                	// string for localization. For more information, see Formatting and Styling.
                	BodyLocArgs string `json:"body_loc_args,omitempty"`
                
                	// TitleLocKey indicates the key to the title string for localization.
                	// Use the key in the app's string resources when populating this value.
                	TitleLocKey string `json:"title_loc_key,omitempty"`
                
                	// TitleLocArgs indicates the string value to replace format specifiers in the title string for
                	// localization. For more information, see
                	// https://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling
                	TitleLocArgs string `json:"title_loc_args,omitempty"`
                }

                  Notification notification message payload

                  type Response

                  type Response struct {
                  	Ok         bool
                  	StatusCode int
                  
                  	// MulticastID a unique ID (number) identifying the multicast message.
                  	MulticastID uint64 `json:"multicast_id"`
                  
                  	// Success number of messages that were processed without an error.
                  	Success int `json:"success"`
                  
                  	// Fail number of messages that could not be processed.
                  	Fail int `json:"failure"`
                  
                  	// CanonicalIDs number of results that contain a canonical registration token.
                  	// A canonical registration ID is the registration token of the last registration
                  	// requested by the client app. This is the ID that the server should use
                  	// when sending messages to the device.
                  	CanonicalIDs int `json:"canonical_ids"`
                  
                  	// Results Array of objects representing the status of the messages processed. The objects are listed in the same order as the request (i.e., for each registration ID in the request, its result is listed in the same index in the response).
                  	// message_id: String specifying a unique ID for each successfully processed message.
                  	// registration_id: Optional string specifying the canonical registration token for the client app that the message was processed and sent to. Sender should use this value as the registration token for future requests. Otherwise, the messages might be rejected.
                  	// error: String specifying the error that occurred when processing the message for the recipient. The possible values can be found in table 9.
                  	Results []Result `json:"results,omitempty"`
                  
                  	// The topic message ID when FCM has successfully received the request and will attempt to deliver to all subscribed devices.
                  	MsgID int `json:"message_id,omitempty"`
                  
                  	// Error that occurred when processing the message. The possible values can be found in table 9.
                  	Err string `json:"error,omitempty"`
                  
                  	// RetryAfter
                  	RetryAfter string
                  }

                    Response represents fcm response message - (tokens and topics)

                    func (*Response) GetRetryAfterTime

                    func (r *Response) GetRetryAfterTime() (time.Duration, error)

                      GetRetryAfterTime converts the retry after response header to a time.Duration

                      type Result

                      type Result struct {
                      	// String specifying a unique ID for each successfully processed message.
                      	MessageID string `json:"message_id"`
                      
                      	// Optional string specifying the canonical registration token for the
                      	// client app that the message was processed and sent to. Sender should
                      	// use this value as the registration token for future requests.
                      	// Otherwise, the messages might be rejected.
                      	RegistrationID string `json:"registration_id"`
                      
                      	// String specifying the error that occurred when processing the message
                      	// for the recipient. The possible values can be found in table 9 here:
                      	// https://firebase.google.com/docs/cloud-messaging/http-server-ref#table9
                      	Error string `json:"error"`
                      }

                        Downstream result from FCM, sent in the "results" field of the Response packet

                        Directories

                        Path Synopsis
                        _examples