Skip to main content

messaging

Package messaging is the Go API for Firebase Cloud Messaging, from the Drift Firebase plugin (github.com/go-drift/drift/plugins/firebase/plugin in drift.yaml).

Reading never blocks: the token is state, and messages are streams. Topic subscriptions and DeleteToken wait for Firebase's servers, so call them from a goroutine: from the UI thread they fail with platform.ErrBlocksUIThread.

import "github.com/go-drift/drift/plugins/firebase/runtime/messaging"

// Send the token to your server whenever it changes.
messaging.Token().AddListener(func() {
    go register(messaging.Token().Value())
})

// A message received while the app runs.
unsub := messaging.Messages().Listen(platform.StreamHandler[messaging.Message]{OnEvent: func(m messaging.Message) {
    drift.Dispatch(func() { showBanner(m) })
}})

// A notification the user tapped, including the one that launched the
// app: taps are queued until the app listens.
messaging.Opens().Listen(platform.StreamHandler[messaging.Message]{OnEvent: func(m messaging.Message) {
    drift.Dispatch(func() { navigate(m.Data["route"]) })
}})

// Messages sent to a topic.
go func() {
    if err := messaging.SubscribeToTopic(ctx, "news"); err != nil { ... }
}()

// On logout: no more messages for this user.
go func() {
    if err := messaging.DeleteToken(ctx); err != nil { ... }
}()

Showing notifications needs the user's permission: platform.Notifications.Permission.Request. On Android, notification messages that arrive while the app is in the background are shown by the system; in the foreground they reach Messages only, on both platforms.

Variables​

ErrInvalidTopic indicates a topic name FCM does not accept.

var ErrInvalidTopic = errors.New("invalid FCM topic name")

func DeleteToken​

func DeleteToken(ctx context.Context) error

DeleteToken deletes this installation's FCM token, so neither messages sent to it nor topic messages arrive: call it on logout. Token is "" when it returns. Firebase issues a new token by the time the app next starts, which Token reports like any new token; send it to your server, and subscribe to the user's topics again, only once a user logs in.

It waits for Firebase's servers, then for the UI thread to apply the change, so call it from a goroutine. On ctx cancellation it returns ctx's error; the deletion may still complete.

func Messages​

func Messages() *platform.Stream[Message]

Messages streams messages received while the app runs: data messages, and notification messages in the foreground. Messages received while no listener is subscribed are queued for the next one.

func Opens​

func Opens() *platform.Stream[Message]

Opens streams notifications the user tapped, including the one that launched the app. Taps while no listener is subscribed are queued for the next one, so subscribe once the app can act on them.

func SubscribeToTopic​

func SubscribeToTopic(ctx context.Context, topic string) error

SubscribeToTopic subscribes this installation to topic, so it receives the messages sent to it. A topic name is 1 to 900 characters from a-z, A-Z, 0-9 and "-_.~%"; any other fails with ErrInvalidTopic.

It waits for Firebase's servers, so call it from a goroutine. On ctx cancellation it returns ctx's error; the subscription may still complete.

func Token​

func Token() *core.Derived[string]

Token is this installation's FCM registration token, "" while there is none: until Firebase issues one, and after DeleteToken. It changes when Firebase rotates it; listen to send the new one to your server. It changes on the UI thread, so a widget can rebuild on it with core.UseListenable.

func UnsubscribeFromTopic​

func UnsubscribeFromTopic(ctx context.Context, topic string) error

UnsubscribeFromTopic undoes SubscribeToTopic. Topic names, waiting and cancellation are as for SubscribeToTopic.

type Message​

Message is a Firebase Cloud Messaging message.

type Message struct {
    // ID is the FCM message ID.
    ID  string
    // Title and Body are the notification's, empty for data-only messages
    // and for taps on Android, where the system showed them.
    Title string
    Body  string
    // Data is the message's custom key/value data.
    Data map[string]string
    // Foreground reports whether a received message arrived while the app
    // was in the foreground. Always false for taps.
    Foreground bool
}

Generated by gomarkdoc