Skip to content

Latest commit

 

History

History
61 lines (33 loc) · 4.91 KB

EXPOSURE_NOTIFICATION_API_USAGE.md

File metadata and controls

61 lines (33 loc) · 4.91 KB
Raw

ExposureNotification API usage

This document outlines the interaction of the SDK with the Exposure Notification Framework version 2 by Apple.

Enabling Exposure Notifications

To enable Exposure Notifications for our app we need to call ENManager.setExposureNotificationEnabled(true:completionHandler:). This will trigger a system popup asking the user to either enable Exposure Notifications on this device or (if another app is active) to switch to our app as active Exposure Notifications app. After the user gave or denied consent the completionHandler will be called.

Disabling Exposure Notifications

To disable Exposure Notifications for our app we need to call ENManager.setExposureNotificationEnabled(false:completionHandler:).

Exporting Temporary Exposure Keys

To retrieve the Temporary Exposure Keys (TEKs) we need to call ENManager.getDiagnosisKeys(completionHandler:). This will trigger a system popup asking the user whether he wants to share the TEKs of the last 14 days with the app. If the user agrees to share the keys with the app the completion handler will get called with a maximum of 14 TEKs.

Detecting Exposure

To check for exposure on a given day we need to call ENManager.detectExposures(configuration:diagnosisKeyURLs:completionHandler:). This method has three parameters:

Exposure Configuration

The ENExposureConfiguration defines the configuration for the Apple scoring of exposures. In our case we ignore most of the scoring methods and only provide:

  • reportTypeNoneMap: this defines what report type a key should bet set if no value is provided by the backend. This is set to .confirmedTest.
  • infectiousnessForDaysSinceOnsetOfSymptoms: This value is obligatory and has to map between the days since onset of symptoms to the degree of infectiousness. Since we score each day equally we set all values to ENInfectiousness.high

Diagnosis key URLs

We need to unzip the file which we got from our backend, store the key file (.bin) and signature file (.sig) locally and pass the local urls to the EN API.

Completion Handler

The completion handler is called with a ENExposureDetectionSummary.

Given a ENExposureDetectionSummary we get ENExposureWindows by calling ENManager.getExposureWindows(summary:completionHandler:). This method has two parameters:

Summary

Here we pass the previously obtained ENExposureDetectionSummary.

Completion Handler

The completion handler is called with [ENExposureWindow].

A ENExposureWindow is a set of Bluetooth scan events from observed beacons within a timespan. A window contains multiple ENScanInstance which are aggregations of attenuation of beacons during a scan.

By grouping the ENExposureWindows by day and then adding up all seconds which lie between our defined attenuation thresholds we can compose the buckets.

The thresholds for the attenuation buckets are loaded from our config server.

To detect an exposure the following formula is used to compute the exposure duration:

durationAttenuationLow * factorLow + durationAtttenuationMedium * factorMedium

If this duration is at least as much as defined in the triggerThreshold a notification is triggered for that day.

Rate limit

We are only allowed to call detectExposures() 6 times within 24h.