The Exposure Notifications framework exposes calibrated attenuations that aim to be device-agnostic. This Bluetooth Low-Energy (BLE) signal strength attenuation, defined as transmit power (TX_power) minus received power (RSSI), can be used as a (noisy) proxy for distance.
TX_power - (
The Exposure Notifications API refers to attenuations in some of the following locations:
Risk scores (both in
The following sections describe the processing involved in gathering and reporting these attenuations.
Calibration: Per-device TX_power and per-device RSSI correction
To ensure that all participating devices compute attenuations in a consistent manner, both transmit power and received power are subject to calibrations.
The calibrated transmitter's
TX_poweris read from the beacon's encrypted payload. Importantly, it is NOT the same as the (unencrypted) TX power present in the lower-level BLE protocol.
The calibrated RSSI is calculated from the measured RSSI by adding a per-device RSSI correction. Importantly, this calibrated RSSI is NOT the same as the (uncalibrated) RSSI reported through the Android Bluetooth framework APIs.
Both transmit and received power calibrations are configurations that are pushed to the devices regularly as more calibration results are received (from Google and partners) and as we refine iPhone-Android consistency. Currently, they depend only on the device model.
For the latest calibration values, download the latest
EN Calibration <Date>.csv.
You can also see which calibration values your device uses by first activating
Exposure Notifications through the API, then searching for the following
keywords in the
Aggregation over a scan: ScanInstance min and average
The Exposure Notifications framework scans for beacons in the background, typically scanning for four seconds every five minutes. Advertisement happens on multiple channels. However, due to an Android BLE framework implementation detail, scanning does not always happen on all three channels. For example, Android devices that use Android versions lower than 9.0 (API version 28) or Exposure Notifications API lower than v1.5 scan only on the first channel (channel 37).
During a scan, a device may detect several identical BLE beacons (up
to once every 250 ms), each with their own attenuation. Those duplicates
are grouped together into a
represented by two numbers: the minimum attenuation, and the average
ScanInstances are exposed through the Exposure Notifications
API starting in version 1.5.
ExposureInformation attenuations (v1 mode): aggregation over a contact period
The API provides one
continuous contact with a diagnosis key. This means that if the same key was
regularly present over several consecutive four-second scans, all of the
ScanInstances are aggregated into a single
AttenuationDurations: three-bucket duration histogram
ExposureInformation exposes a three-bucket histogram of attenuations:
getAttenuationDurationsInMinutes returns the durations for which the minimum
attenuation of exposures fell in three different buckets:
< low threshold
Between low threshold and high threshold
> high threshold
You can configure the two thresholds using
If scans happen exactly every five minutes, the durations accumulated in
those buckets will be 5 times the number of those exposures'
whose attenuation falls in that bucket.
ExposureInformation attenuationValue: duration-weighted averaging
duration-weighted averaging of the
ScanInstance minimum attenuation values.
ExposureSummary's attenuationDurations (v1 mode): aggregation over all exposures
ExposureSummary represents a summary over all
exposures. Attenuations over all exposures are summarized in
as the aggregate of all
If scans happen exactly every five minutes, the durations accumulated in those
buckets will be 5 times the number of
ScanInstances whose minimum attenuation
falls in that bucket.
Two simultaneous sightings (
ScanInstances) of two different keys both count toward the total time.
ExposureSummary, the buckets are currently capped at 30 minutes.
Attenuations as distance proxy
Attenuation is a very noisy proxy of distance. A very low attenuation will
indicate a very high probability of a short distance, but a low attenuation can
be caused by many phenomena and is not always indicative of a long distance.
thresholds or risk score multipliers, it's necessary to make a tradeoff between
precision and recall.