ExposureNotificationClient

public interface ExposureNotificationClient implements HasApiKey<Api.ApiOptions.NoOptions>

Interface for contact tracing APIs.

Constant Summary

String ACTION_EXPOSURE_NOTIFICATION_SETTINGS Activity action which shows the exposure notification settings screen.
String ACTION_EXPOSURE_NOT_FOUND Action which will be invoked via a BroadcastReceiver as a callback when matching has finished and no matches were found.
String ACTION_EXPOSURE_STATE_UPDATED Action which will be invoked via a BroadcastReceiver as a callback when the user has an updated exposure status.
String ACTION_SERVICE_STATE_UPDATED Action which will be invoked via a BroadcastReceiver when the user modifies the state of exposure notifications via the Google Settings page.
String EXTRA_EXPOSURE_SUMMARY This constant is deprecated. ExposureSummary is no longer provided when using the getExposureWindows() API. Instead, use getDailySummaries(DailySummariesConfig).
String EXTRA_SERVICE_STATE Boolean extra attached to the ACTION_SERVICE_STATE_UPDATED broadcast signifying whether the service is enabled or disabled.
String EXTRA_TOKEN This constant is deprecated. Tokens are no longer used. Instead, prefer using the tokenless versions of provideDiagnosisKeys(DiagnosisKeyFileProvider), getExposureWindows(), and getDailySummaries(DailySummariesConfig).
String TOKEN_A This constant is deprecated. Tokens are no longer used. Instead, prefer using the tokenless versions of provideDiagnosisKeys(DiagnosisKeyFileProvider), getExposureWindows(), and getDailySummaries(DailySummariesConfig).

Public Method Summary

abstract boolean
deviceSupportsLocationlessScanning()
Checks whether the device supports Exposure Notification BLE scanning without requiring location to be enabled first.
abstract Task<Integer>
abstract Task<List<DailySummary>>
getDailySummaries(DailySummariesConfig dailySummariesConfig)
Retrieves the per-day exposure summaries associated with the provided configuration.
abstract Task<DiagnosisKeysDataMapping>
abstract Task<List<ExposureInformation>>
getExposureInformation(String token)
This method is deprecated. When using the ExposureWindow API, use getExposureWindows() instead.
abstract Task<ExposureSummary>
getExposureSummary(String token)
This method is deprecated. When using the ExposureWindow API, use getDailySummaries(DailySummariesConfig) instead.
abstract Task<List<ExposureWindow>>
getExposureWindows()
Retrieves the list of exposure windows corresponding to the TEKs given to provideDiagnosisKeys(DiagnosisKeyFileProvider).
abstract Task<List<ExposureWindow>>
getExposureWindows(String token)
This method is deprecated. Tokens are no longer used. Instead, prefer using the tokenless version of getExposureWindows().
abstract Task<PackageConfiguration>
getPackageConfiguration()
Retrieves the associated PackageConfiguration for the calling package.
abstract Task<Set<ExposureNotificationStatus>>
getStatus()
Gets the current Exposure Notification status.
abstract Task<List<TemporaryExposureKey>>
getTemporaryExposureKeyHistory()
Gets TemporaryExposureKey history to be stored on the server.
abstract Task<Long>
getVersion()
Gets the current Exposure Notification version.
abstract Task<Boolean>
isEnabled()
Indicates whether contact tracing is currently running for the requesting app.
abstract Task<Void>
provideDiagnosisKeys(List<File> keyFiles)
This method is deprecated. Prefer the DiagnosisKeyFileProvider version of this method instead, which scales better when a large number of files are passed at the same time.
abstract Task<Void>
provideDiagnosisKeys(DiagnosisKeyFileProvider provider)
Provides diagnosis key files for exposure checking.
abstract Task<Void>
provideDiagnosisKeys(List<File> keyFiles, ExposureConfiguration configuration, String token)
This method is deprecated. Tokens and configuration are no longer used. Instead, prefer using the tokenless, configuration-less version of provideDiagnosisKeys(DiagnosisKeyFileProvider).
abstract Task<Void>
setDiagnosisKeysDataMapping(DiagnosisKeysDataMapping diagnosisKeysMetadataMapping)
Sets the diagnosis keys data mapping if it wasn't already changed recently.
abstract Task<Void>
start()
Starts BLE broadcasts and scanning based on the defined protocol.
abstract Task<Void>
stop()
Disables advertising and scanning.

Constants

public static final String ACTION_EXPOSURE_NOTIFICATION_SETTINGS

Activity action which shows the exposure notification settings screen.

Constant Value: "com.google.android.gms.settings.EXPOSURE_NOTIFICATION_SETTINGS"

public static final String ACTION_EXPOSURE_NOT_FOUND

Action which will be invoked via a BroadcastReceiver as a callback when matching has finished and no matches were found. Also see EXTRA_TOKEN, which will be included in this broadcast.

Constant Value: "com.google.android.gms.exposurenotification.ACTION_EXPOSURE_NOT_FOUND"

public static final String ACTION_EXPOSURE_STATE_UPDATED

Action which will be invoked via a BroadcastReceiver as a callback when the user has an updated exposure status. Also see EXTRA_EXPOSURE_SUMMARY and EXTRA_TOKEN, which will be included in this broadcast.

Constant Value: "com.google.android.gms.exposurenotification.ACTION_EXPOSURE_STATE_UPDATED"

public static final String ACTION_SERVICE_STATE_UPDATED

Action which will be invoked via a BroadcastReceiver when the user modifies the state of exposure notifications via the Google Settings page. EXTRA_SERVICE_STATE will be included as part of this broadcast.

Constant Value: "com.google.android.gms.exposurenotification.ACTION_SERVICE_STATE_UPDATED"

public static final String EXTRA_EXPOSURE_SUMMARY

This constant is deprecated.
ExposureSummary is no longer provided when using the getExposureWindows() API. Instead, use getDailySummaries(DailySummariesConfig).

Extra attached to the ACTION_EXPOSURE_STATE_UPDATED broadcast, giving a summary of the exposure details detected. Also see getExposureSummary(String).

Constant Value: "com.google.android.gms.exposurenotification.EXTRA_EXPOSURE_SUMMARY"

public static final String EXTRA_SERVICE_STATE

Boolean extra attached to the ACTION_SERVICE_STATE_UPDATED broadcast signifying whether the service is enabled or disabled.

Constant Value: "com.google.android.gms.exposurenotification.EXTRA_SERVICE_STATE"

public static final String EXTRA_TOKEN

This constant is deprecated.
Tokens are no longer used. Instead, prefer using the tokenless versions of provideDiagnosisKeys(DiagnosisKeyFileProvider), getExposureWindows(), and getDailySummaries(DailySummariesConfig).

Extra attached to the ACTION_EXPOSURE_STATE_UPDATED broadcast, providing the token associated with the provideDiagnosisKeys(DiagnosisKeyFileProvider) request.

Constant Value: "com.google.android.gms.exposurenotification.EXTRA_TOKEN"

public static final String TOKEN_A

This constant is deprecated.
Tokens are no longer used. Instead, prefer using the tokenless versions of provideDiagnosisKeys(DiagnosisKeyFileProvider), getExposureWindows(), and getDailySummaries(DailySummariesConfig).

Token to be used with ExposureWindows API. Must be used with provideDiagnosisKeys(DiagnosisKeyFileProvider) request when later using getExposureWindows().

Constant Value: "TYZWQ32170AXEUVCDW7A"

Public Methods

public abstract boolean deviceSupportsLocationlessScanning ()

Checks whether the device supports Exposure Notification BLE scanning without requiring location to be enabled first.

public abstract Task<Integer> getCalibrationConfidence ()

Gets CalibrationConfidence of the current device.

public abstract Task<List<DailySummary>> getDailySummaries (DailySummariesConfig dailySummariesConfig)

Retrieves the per-day exposure summaries associated with the provided configuration.

A valid configuration must be provided to compute the summaries.

public abstract Task<DiagnosisKeysDataMapping> getDiagnosisKeysDataMapping ()

Retrieves the current DiagnosisKeysDataMapping.

public abstract Task<List<ExposureInformation>> getExposureInformation (String token)

This method is deprecated.
When using the ExposureWindow API, use getExposureWindows() instead.

Gets detailed information about exposures that have occurred related to the provided token, which should match the token provided in provideDiagnosisKeys(DiagnosisKeyFileProvider).

When multiple ExposureInformation objects are returned, they can be:

  • Multiple encounters with a single diagnosis key.
  • Multiple encounters with the same device across key rotation boundaries.
  • Encounters with multiple devices.
Records of calls to this method will be retained and viewable by the user.

public abstract Task<ExposureSummary> getExposureSummary (String token)

This method is deprecated.
When using the ExposureWindow API, use getDailySummaries(DailySummariesConfig) instead.

Gets a summary of the exposure calculation for the token, which should match the token provided in provideDiagnosisKeys(DiagnosisKeyFileProvider).

public abstract Task<List<ExposureWindow>> getExposureWindows ()

Retrieves the list of exposure windows corresponding to the TEKs given to provideDiagnosisKeys(DiagnosisKeyFileProvider).

Long exposures to one TEK are split into windows of up to 30 minutes of scans, so a given TEK may lead to several exposure windows if beacon sightings for it spanned more than 30 minutes. The link between them (the fact that they all correspond to the same TEK) is lost because those windows are shuffled before being returned and the underlying TEKs are not exposed by the API.

public abstract Task<List<ExposureWindow>> getExposureWindows (String token)

This method is deprecated.
Tokens are no longer used. Instead, prefer using the tokenless version of getExposureWindows().

Retrieves the list of exposure windows corresponding to the TEKs given to provideKeys with token=TOKEN_A.

Long exposures to one TEK are split into windows of up to 30 minutes of scans, so a given TEK may lead to several exposure windows if beacon sightings for it spanned more than 30 minutes. The link between them (the fact that they all correspond to the same TEK) is lost because those windows are shuffled before being returned and the underlying TEKs are not exposed by the API.

The provided token must be TOKEN_A.

public abstract Task<PackageConfiguration> getPackageConfiguration ()

Retrieves the associated PackageConfiguration for the calling package. Note that this value can be null if no configuration was when starting.

public abstract Task<Set<ExposureNotificationStatus>> getStatus ()

Gets the current Exposure Notification status.

public abstract Task<List<TemporaryExposureKey>> getTemporaryExposureKeyHistory ()

Gets TemporaryExposureKey history to be stored on the server.

This should only be done after proper verification is performed on the client side that the user is diagnosed positive. Each key returned will have an unknown transmission risk level, clients should choose an appropriate risk level for these keys before uploading them to the server.

The keys provided here will only be from previous days; keys will not be released until after they are no longer an active exposure key.

This shows a user permission dialog for sharing and uploading data to the server.

public abstract Task<Long> getVersion ()

Gets the current Exposure Notification version.

public abstract Task<Boolean> isEnabled ()

Indicates whether contact tracing is currently running for the requesting app.

public abstract Task<Void> provideDiagnosisKeys (List<File> keyFiles)

This method is deprecated.
Prefer the DiagnosisKeyFileProvider version of this method instead, which scales better when a large number of files are passed at the same time.

Provides a list of diagnosis key files for exposure checking. The files are to be synced from the server. Old diagnosis keys (for example older than 14 days), will be ignored.

Diagnosis keys will be stored and matching will be performed in the near future, after which you’ll receive a broadcast with the ACTION_EXPOSURE_STATE_UPDATED action. If no matches are found, you'll receive an ACTION_EXPOSURE_NOT_FOUND action.

The diagnosis key files must be signed appropriately. Results from this request can also be queried at any time via getExposureWindows() and getDailySummaries(DailySummariesConfig).

After the result Task has returned, keyFiles can be deleted.

Results remain for 14 days.

public abstract Task<Void> provideDiagnosisKeys (DiagnosisKeyFileProvider provider)

Provides diagnosis key files for exposure checking. The files are to be synced from the server. Old diagnosis keys (for example older than 14 days), will be ignored.

Diagnosis keys will be stored and matching will be performed in the near future, after which you’ll receive a broadcast with the ACTION_EXPOSURE_STATE_UPDATED action. If no matches are found, you'll receive an ACTION_EXPOSURE_NOT_FOUND action.

The diagnosis key files must be signed appropriately. Results from this request can also be queried at any time via getExposureWindows() and getDailySummaries(DailySummariesConfig).

After the result Task has returned, files can be deleted.

Results remain for 14 days.

public abstract Task<Void> provideDiagnosisKeys (List<File> keyFiles, ExposureConfiguration configuration, String token)

This method is deprecated.
Tokens and configuration are no longer used. Instead, prefer using the tokenless, configuration-less version of provideDiagnosisKeys(DiagnosisKeyFileProvider).

Provides a list of diagnosis key files for exposure checking. The files are to be synced from the server. Old diagnosis keys (for example older than 14 days), will be ignored.

Diagnosis keys will be stored and matching will be performed in the near future, after which you’ll receive a broadcast with the ACTION_EXPOSURE_STATE_UPDATED action. If no matches are found, you'll receive an ACTION_EXPOSURE_NOT_FOUND action.

The diagnosis key files must be signed appropriately. Exposure configuration options can be provided to tune the matching algorithm. A unique token for this batch can also be provided, which will be used to associate the matches with this request as part of getExposureSummary(String) and getExposureInformation(String). Alternatively, the same token can be passed in multiple times to concatenate results.

After the result Task has returned, keyFiles can be deleted.

Results for a given token remain for 14 days.

public abstract Task<Void> setDiagnosisKeysDataMapping (DiagnosisKeysDataMapping diagnosisKeysMetadataMapping)

Sets the diagnosis keys data mapping if it wasn't already changed recently.

If called twice within 7 days, the second call will have no effect and will raise an exception with status code FAILED_RATE_LIMITED.

public abstract Task<Void> start ()

Starts BLE broadcasts and scanning based on the defined protocol.

If not previously started, this shows a user dialog for consent to start exposure detection and get permission.

Callbacks regarding exposure status will be provided via a BroadcastReceiver. Clients should register a receiver in their AndroidManifest which can handle the following action:

  • com.google.android.gms.exposurenotification.ACTION_EXPOSURE_STATE_UPDATED
This receiver should also be guarded by the com.google.android.gms.nearby.exposurenotification.EXPOSURE_CALLBACK permission so that other apps are not able to fake this broadcast.

public abstract Task<Void> stop ()

Disables advertising and scanning. Contents of the database and keys will remain.

If the client app has been uninstalled by the user, this will be automatically invoked and the database and keys will be wiped from the device.