DP3T-SDK for iOS

DP3T

The Decentralised Privacy-Preserving Proximity Tracing (DP-3T) project is an open protocol for COVID-19 proximity tracing using Bluetooth Low Energy functionality on mobile devices that ensures personal data and computation stays entirely on an individual's phone. It was produced by a core team of over 25 scientists and academic researchers from across Europe. It has also been scrutinized and improved by the wider community.

DP-3T is a free-standing effort started at EPFL and ETHZ that produced this protocol and that is implementing it in an open-sourced app and server.

Introduction

This is the implementation of the DP-3T protocol using the Exposure Notification Framework of Apple/Google. Only approved government public health authorities can access the APIs. Therefore, using this SDK will result in an API error unless you were granted the com.apple.developer.exposure-notification entitlement by Apple. We are using Exposure Notification Framework version 2, and the deployment target is therefore set to 13.7.

Our prestandard solution that is not using the Apple/Google framework can be found under the tag prestandard.

Repositories

Android SDK & Calibration app: dp3t-sdk-android
iOS SDK & Calibration app: dp3t-sdk-ios
Backend SDK: dp3t-sdk-backend

For an example project using the SDK look at the Swiss contact tracing app SwissCovid.

Further Documentation

The full set of documents for DP3T is at https://github.com/DP-3T/documents. Please refer to the technical documents and whitepapers for a description of the implementation.

DP3T Exposure Score Calculation

The in-depth technical specification of the methodology used for the score calculation can be found here.

A description of the usage of the Apple Exposure Notification API can be found here.

Calibration App

Included in this repository is a Calibration App that can run, debug and test the SDK directly without implementing it in a new app first. Various parameters of the SDK are exposed and can be changed at runtime. Additionally it provides an overview of how to use the SDK.

Function overview

Initialization

Name	Description	Function Name
init	Initializes the SDK and configures it	`initialize(applicationDescriptor:urlSession:backgroundHandler:federationGateway)`

Methods & Properties

Name	Description	Function/Variable Name
startTracing	Starts EN tracing	`func startTracing(completionHandler:)`
stopTracing	Stops EN tracing	`func stopTracing(completionHandler:)`
sync	Pro-actively triggers sync with backend to refresh exposed list	`func sync(callback:)`
status	Returns a TracingState-Object describing the current state. This contains: - `numberOfHandshakes` : `Int` - `trackingState` : `TrackingState` - `lastSync` : `Date` - `infectionStatus`:`InfectionStatus` - `backgroundRefreshState`:`UIBackgroundRefreshStatus`	`func status(callback:)`
iWasExposed	This method must be called upon positive test.	`func iWasExposed(onset:authentication:isFakeRequest:callback:)`
federationGateway	Specifies whether keys should be exchanged with other compatible countries. Possible values are 'yes', 'no', 'unspecified' (default)	`var federationGateway`
reset	Removes all SDK related data	`func reset()`

Installation

Swift Package Manager

DP3T-SDK is available through Swift Package Manager

Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/DP-3T/dp3t-sdk-ios.git", .branch("develop"))
]

Cocoapods

DP3T-SDK is available through Cocoapods

Add the following to your Podfile:

pod 'DP3TSDK', => '2.3.0'

This version points to the HEAD of the develop branch and will always fetch the latest development status. Future releases will be made available using semantic versioning to ensure stability for depending projects.

Using the SDK

In order to use the SDK with iOS 14 you need to specify the region for which the app works and the version of the Exposure Notification Framework which should be used.

This is done by adding ENDeveloperRegion as an Info.plist property with the according ISO 3166-1 country code as its value. The SDK works with EN Framework version 2 and therefore we need to specify ENAPIVersion with a value of 2 in the Info.plist.

Backend

Starting with DP3T SDK version 2.0 the required backend version is 2.0.

Initialization

In your AppDelegate in the didFinishLaunchingWithOptions function you have to initialize the SDK.

let url = URL(string: "https://example.com/your/api/")!
DP3TTracing.initialize(with: .init(appId: "com.example.your.app", 
                                   bucketBaseUrl: url, 
                                   reportBaseUrl: url))

Certificate pinning

The SDK accepts a URLSession as an optional argument to the initializer. This can be used to enable certificate pinning. If no session is provided URLSession.shared will be used.

Start / Stop tracing

To start and stop tracing use

DP3TTracing.startTracing()
DP3TTracing.stopTracing()

Checking the current tracing status

let status = DP3TTracing.status

The TracingState object contains all information regarding the current tracing status.

To receive callbacks and notifications when the state changes, you should assign a delegate object conforming to DP3TTracingDelegate:

DP3TTracing.delegate = yourDelegateObject // weak retained by the SDK

// Delegate method
func DP3TTracingStateChanged(_ state: TracingState) {

}

The SDK will call your delegate on every state change, this includes: Handshake detection, start/stop of tracing, change in exposure, errors...

Report user exposed

DP3TTracing.iWasExposed(onset: Date(), authentication: .none) { result in
	// Handle result here
}

Sync with backend for exposed user

The SDK automatically syncs with the backend for new exposed users by scheduling a background task.

DP3TTracing.sync() { result in
	// Handle result here
}

Background Tasks

The SDK supports iOS 13 background tasks. It uses the provided exposure-notification background processing task as well as the BGAppRefreshTask. To enable them the app has to support the Background process and Background fetch capabilities and include org.dpppt.exposure-notification and org.dpppt.refresh in the BGTaskSchedulerPermittedIdentifiers Info.plist property.

Info.plist sample:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>org.dpppt.exposure-notification</string>
  <string>org.dpppt.refresh</string>
</array>
<key>UIBackgroundModes</key>
<array>
  <string>processing</string>
  <string>fetch</string>
</array>

If a DP3TBackgroundHandler was passed to the SDK on initialisation it will be called on each background task execution by the SDK.

Apps using the DP3T-SDK for iOS

Name	Country	Source code	Store	Release-Date
SwissCovid	Switzerland	Github	AppStore	25. Mai 2020
ASI	Ecuador	minka.gob.ec	AppStore	2. August 2020
Hoia	Estonia	koodivaramu.eesti.ee	AppStore	19. August 2020
STAYAWAY COVID	Portugal	Github	AppStore	28. August 2020
Radar COVID	Spain	Github	AppStore

If your project/country is not yet listed but uses the DP3T-SDK feel free to send a pull-request to add it to the README.

License

This project is licensed under the terms of the MPL 2 license. See the LICENSE file.