Migrate to Go Admin SDK v4

Starting from version 4.0.0, the Firebase Admin SDK for Go has opted into Go modules. Also, there are breaking changes in error handling and semantics.

Installation changes

Conforming to modules best practices, the SDK's major version has been appended to the package name. This change results in the following package name updates:

  • firebase.google.com/go → firebase.google.com/go/v4
  • firebase.google.com/go/auth → firebase.google.com/go/v4/auth
  • firebase.google.com/go/db → firebase.google.com/go/v4/db
  • firebase.google.com/go/iid → firebase.google.com/go/v4/iid
  • firebase.google.com/go/messaging → firebase.google.com/go/v4/messaging

Developers already using modules

Use the versioned package name to install the latest version of the SDK.

# Install the latest version:
go install firebase.google.com/go/v4@latest

# Or install a specific version:
go install firebase.google.com/go/[email protected]

The same versioned package name must be used in the source code when importing the SDK.

package helloworld

import (
        "firebase.google.com/go/v4"
        "firebase.google.com/go/v4/auth"
        "firebase.google.com/go/v4/messaging"
)

To install an earlier version, use the old (unversioned) package name with an explicit version qualifier.

# Notice the @v3 suffix.
# This instructs Go tools to fetch the latest v3.x release of the SDK.
go get firebase.google.com/go@v3

Developers not currently using modules

Developers who haven't opted into modules yet can continue to install the SDK using the unversioned package name.

go get firebase.google.com/go

Note, however, that this fetches the latest version of the SDK (v4 or later) which contains other breaking API changes.

General error handling changes

The v4 SDK introduces a new errorutils package that provides functions for handling platform-level error conditions. In the event an error was caused by a backend service error, you can access the original error response by calling the new function errorutils.HTTPResponse(). You can use the functions in this package with errors returned by any API in the SDK.

Authentication API changes

  • Added new error handling functions to be used in conjunction with VerifyIDToken() and VerifySessionCookie() APIs:
    • IsIDTokenInvalid()
    • IsIDTokenExpired()
    • IsSessionCookieInvalid()
    • IsSessionCookieExpired()
    • IsCertificateFetchFailed()
  • Deprecated:
    • IsProjectNotFound()
    • IsUnknown()
    • IsInsufficientPermission()
    • IsInvalidEmail()

FCM API changes

  • Renamed the type messaging.WebpushFCMOptions to messaging.WebpushFcmOptions.
  • Added:
    • IsThirdPartyAuthError()
    • IsQuotaExceeded()
    • IsSenderIDMismatch()
    • IsUnregistered()
    • IsUnavailable()
  • Deprecated:
    • IsInvalidAPNSCredentials()
    • IsMessageRateExceeded()
    • IsMismatchedCredential()
    • IsRegistrationTokenNotRegistered()
    • IsServerUnavailable()
    • IsTooManyTopics()
    • IsUnknown()

IID API changes

All error handling functions currently available in the iid package are now deprecated. Use the corresponding error handling functions provided in the errorutils package instead.