Exposure Notification release notes

Stay organized with collections Save and categorize content based on your preferences.

v1.9, December 2021

Version 1.9 of the Exposure Notifications API introduces variantOfConcern, which provides the option of labeling TEKs associated with variants of concern.

v1.8, January 2021

Version 1.8 of the Exposure Notifications API includes:

Preauthorization of TEK release

This feature allows client apps to optionally request that users preauthorize sharing their anonymous keys in case of a positive test result. During enrollment, the app can request that users set up automatic sharing by calling requestPreAuthorizedTemporaryExposureKeyHistory() and displaying the consent screen via startResolutionForResult(), if required. If consent is given, the app is able to retrieve keys once in the next 5 days. This feature is useful when a user had a test done recently, or is about to be tested for COVID-19.

preauthorization dialog

If a user denies consent, then the client app receives the FAILED_REJECTED_OPT_IN status code.

By requesting preauthorization to share the user's keys in case of a positive test, other users that might have come in contact with them can receive notifications without the user’s action. When the app wants to upload keys, for example if a test result is positive, it should call requestPreAuthorizedTemporaryExposureKeyRelease(). The keys are delivered via a broadcast with the ACTION_PRE_AUTHORIZE_RELEASE_PHONE_UNLOCKED action, the moment the user unlocks their phone. A notification is also displayed to the user.

preautorization notification

getTemporaryExposureKeyHistory() foreground check

If a client is not in the foreground when getTemporaryExposureKeyHistory() is invoked, then the FAILED_NOT_IN_FOREGROUND error code is immediately returned. This prevents unexpected user experiences where the dialog could be shown on top of other, non-Exposure Notification-related tasks, and also aligns with the iOS implementation.

Settings UX changes

"Exposure checks" and "Delete random IDs"

The Exposure checks and the Delete random IDs button have both been moved from the main settings list to the overflow menu. There have been no functional changes to these options.

settings overflow

App details UX

When tapping an app from the main settings screen, a user is now directed to a details screen where they can open the app or modify settings associated with the requestPreAuthorizedTemporaryExposureKeyHistory() API when applicable.

app details

Monthly service enabled notifications

Notifications informing the user that Exposure Notifications are active have been moved from weekly to monthly.

provideDiagnosisKey() quota changes

If the call to provideDiagnosisKeys() fails for any reason, it will no longer be counted against the quota for that method, allowing client applications to freely retry if desired.

Deprecation of deviceSupportsLocationlessScanning()

deviceSupportsLocationlessScanning() is deprecated in favor of the getStatus() API, which provides more details about whether Exposure Notifications can currently be supported on the device.

API call timeouts

All API calls now time out after 2 minutes, after which a failure response will be delivered to the caller. provideDiagnosisKeys() is special cased to time out after 60 minutes as a large number of keys and files can take a significant amount of time to process on low-end devices.

v1.7.2, October 2020

Version 1.7.2 of the Exposure Notifications API is a small bug fix release on top of v1.7 including the following:

  • Bug fix which allows for passing in a large number of key files to provideDiagnosisKeys on low-end devices without crashing the service.

v1.7, September 2020

Version 1.7 of the Exposure Notifications API includes the following changes, which aim to fix common pain points and address some minor pending items:

  • New getStatus() method
  • Discarding of ExposureWindow objects with infectiousness=NONE and reportType=REVOKED for computing DailySummaries risk scores.
  • App uninstall cleanup
  • Preparing for future onboarding flow on the Play Store
  • Fixes for crashes and bugs, including fixes for localization string in settings

New getStatus() method

We received feedback that the process was cumbersome for determining whether Exposure Notifications can be used on a given device, because it required first checking whether the device has the right settings enabled.

The new getStatus() method moves that complexity to the API level and returns a ExposureNotificationStatus value. This makes it easier and more straightforward to determine whether Exposure Notifications is usable on a device.

Discarding of ExposureWindow objects with infectiousness=NONE and reportType=REVOKED

Exposures to other users should not contribute to the DailySummaries risk value if their diagnosis keys are mapped by configuration to either of the following ExposureWindow values:

  • infectiousness=NONE: Their days since onset of symptoms correspond with very low infectiousness

  • reportType=REVOKED: They have been revoked

Prior to Exposure Notifications v1.7, we recommended assigning a weight of 0 for exposure data with these values. Because these factors wouldn’t contribute to the final count, we added the optimization to drop them automatically for risk value computation.

App uninstall cleanup

When an app is uninstalled, the Exposure Notifications system deletes pending matching requests to keep any residual untraceable tokens from remaining on the device.

Preparing for future onboarding flow on the Play Store

We added an Exposure Notifications API component that enables a future optimization of the app onboarding flow on the Google Play Store. This feature will allow users to enable Exposure Notifications on their device during the installation process of an Exposure Notifications app.

New six-hour WakeUpService cadence

WakeUpService now runs every six hours instead of daily.

This change in frequency should help apps to not to be terminated based on system resource optimizations.

v1.6, August 2020

Version 1.6 of the Exposure Notifications API is a patch update to v1.5 that includes:

  • Addition of data to the existing ExposureWindow class, to help you optionally design your own definitions of meaningful exposures
  • Daily exposure summaries
  • Locationless scanning
  • System user experience changes
  • The new getVersion() method

ExposureWindow now has infectiousness and calibrationConfidence

In v1.6, ExposureWindow adds two new fields to allow public health authorities (PHAs) to estimate the risk score for a set of exposure data:

infectiousness

infectiousness represents the level of virality associated with a given key.

calibrationConfidence

We have gradually improved the calibrated values for supported devices, now based on internal calibrations and statistical modeling. In v1.5, we started including calibration confidence in advertisements, and now with v1.6 you can benefit from these enhancements.

calibrationConfidence provides an estimation of the level of accuracy of the calibration associated with the exposure’s attenuation.

New diagnosis key data mapping configuration

We have added the data structure DiagnosisKeysDataMapping, which contains configuration parameters to map diagnosis key data to ExposureWindow fields. In v1.6, these parameters are applied at matching time, when calling provideDiagnosisKeys(). Changing the configuration via setDiagnosisKeysDataMapping() won't modify ExposureWindows for keys provided in past calls, but we might change this behavior in future versions. If setDiagnosisKeysDataMapping() is called twice within 7 days, the second call has no effect and raises an exception with status code FAILED_RATE_LIMITED.

Daily exposure summaries

v1.6 completes the new set of risk score computation functionality started with v1.5. With the addition of getDailySummaries() and the related data structures DailySummaryConfig, DailySummary, and ExposureSummaryData, you now have a predefined algorithm to compute risk score based on PHA-defined thresholds and weights for the different parameters in ExposureWindow.

Note on DailySummaryConfig: In v1.6, any instances of ExposureWindow objects with infectiousness=NONE may go into your daily exposure summary computation. When calling getDailySummaries(), and a weight is specified for infectiousness=NONE in the DailySummaryConfig object, we recommend setting the weight to 0 because NONE indicates no risk of exposure. A future version of the API may disregard a mapping value for infectiousness=NONE, because ExposureWindow with infectiousness=NONE may be dropped before computing the risk scores.

Locationless scanning

With Android 11, version 1.6 and higher of Exposure Notifications works without having to enable Location Services. This means there are now additional cases in which it is not necessary to prompt users to manually enable this setting.

To simplify checking when locationless scanning is available on the device, we have updated the SDK (v1.6.1) to include deviceSupportsLocationlessScanning(). This method returns a boolean value indicating whether a given device supports locationless scanning. (Note that as of the v1.7 SDK, we recommend checking via a different approach.)

Report type transitions of previously reported TEKs

v1.6 supports changing the reportType value associated with a particular Temporary Exposure Key (TEK), allowing public health authorities (PHAs) to update reported cases to a more accurate state as they gather more data. Because TEKs can go through a single report type transition, additional transitions will be rejected if more than one is attempted. The following transitions are supported:

SELF_REPORT -> CONFIRMED_TEST, CONFIRMED_CLINICAL_DIAGNOSIS, REVOKED

CONFIRMED_TEST -> CONFIRMED_CLINICAL_DIAGNOSIS, REVOKED

System user experience changes

We have added a new tile to the Settings page linking to guidance when a user has Exposure Notifications permanently disabled by the PHA’s server.

New API method: getVersion()

V1.6 includes the new getVersion() function, which provides information about the module version installed on the user device.

Debug mode changes

We have added a new option in debug mode: Return today’s TEK with shortened rolling period. This functionality enables testing the behavior of early TEK release for getTemporaryExposureKeyHistory(). This enables you to test the compatibility of your app and server with early TEK release, thereby allowing you to prepare in advance for this feature before it is activated in production with upcoming updates.

v1.5, July 2020

Version 1.5 of the Exposure Notifications API started rolling out on 2020-07-09. There are no behavior changes in existing functionality, but we have introduced bug fixes and new features that aim to provide developers with more data and make the API easier to test and debug. See the following sections for the new additions.

ExposureWindow replaces ExposureInformation

Version 1.5 introduces the ExposureWindow class. The class provides a new way to determine the risk associated with an exposure, replacing ExposureInformation and ExposureSummary. To use the new method, use the ExposureWindow mode. Note the following changes:

ExposureWindow mode and v1 mode

We have introduced the use of a special token to switch between working modes. The default behavior for apps that were built for v1 is to continue working as designed when running on v1.5—we call this v1 mode. You can opt to use ExposureWindow mode by calling provideDiagnosisKeys() with the special value for the parameter token=TOKEN_A.

Multiple batch group support for provideDiagnosisKeys

provideDiagnosisKeys() will support passing multiple batch groups (signatories) in a single method call, as a way to support different server interoperability use cases.

Debug mode changes

The Debug mode changed with version 1.5 of the API. You can read more about the changes in the Debug mode topic.

System user experience changes

Settings screen updates for more clarity, transparency, and control: We have made it easier for users to understand when Exposure Notifications are on or off, and added a simple way to enable or disable the feature from settings (Settings > Google > COVID-19 Exposure Notifications). This includes:

  • Adding a new indicator at the top of settings to make it clear when the feature is on or off.
  • Removing most of the content and options when no Exposure Notifications app is installed, since they aren’t relevant.

  • Adding a new option to reactivate Exposure Notifications from Settings: users need to enable Exposure Notifications from the app before the API is enabled on the device. We introduced the capability to toggle Exposure Notifications off through Settings in previous versions. As of v1.5, users can also turn it back on from the same setting.


    Figure 1. Updated Settings screen

  • App force-stop improvements: if an app has been force-stopped in the background, the Exposure Notifications service will wake it up again automatically.

Reference documentation updates

The reference implementation app has been adjusted to use ExposureWindow mode. We also updated the reference diagnosis key server implementation to use the verification server reference.

For an account on recent changes in the documentation, refer to the documentation change log.