{"id":13629867,"url":"https://github.com/MohGovIL/rn-contact-tracing","last_synced_at":"2025-04-17T13:30:34.597Z","repository":{"id":38901469,"uuid":"255036568","full_name":"MohGovIL/rn-contact-tracing","owner":"MohGovIL","description":"React Native Library For Contact Tracing Over BLE (Bluetooth Low Energy) To Fight COVID-19 Pandemic","archived":false,"fork":false,"pushed_at":"2023-01-06T03:56:49.000Z","size":6861,"stargazers_count":59,"open_issues_count":55,"forks_count":16,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-04-16T16:58:41.481Z","etag":null,"topics":["ble-native","ble-scanning","bluetooth-low-energy","contact-tracing","covid-19","covid19","react-native"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MohGovIL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-12T08:05:31.000Z","updated_at":"2023-01-12T10:53:39.000Z","dependencies_parsed_at":"2023-02-05T06:31:48.913Z","dependency_job_id":null,"html_url":"https://github.com/MohGovIL/rn-contact-tracing","commit_stats":null,"previous_names":["wix-incubator/rn-contact-tracing"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohGovIL%2Frn-contact-tracing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohGovIL%2Frn-contact-tracing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohGovIL%2Frn-contact-tracing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohGovIL%2Frn-contact-tracing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MohGovIL","download_url":"https://codeload.github.com/MohGovIL/rn-contact-tracing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249344734,"owners_count":21254723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble-native","ble-scanning","bluetooth-low-energy","contact-tracing","covid-19","covid19","react-native"],"created_at":"2024-08-01T22:01:22.224Z","updated_at":"2025-04-17T13:30:34.065Z","avatar_url":"https://github.com/MohGovIL.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 font-weight=bold align=\"center\"\u003eRN-Contact-Tracing\u003c/h1\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/rn-contact-tracing\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/rn-contact-tracing\" alt=\"NPM version\"\u003e\u003c/a\u003e\n  \u003ca href=\"/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/rn-contact-tracing\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MohGovIL/rn-contact-tracing/actions?query=workflow%3ACI\"\u003e\u003cimg src=\"https://github.com/MohGovIL/rn-contact-tracing/workflows/CI/badge.svg?style=flat-square\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ch3 font-weight=bold align=\"center\"\u003e  WIP Library - Don't Use in Production\u003c/h3\u003e\n\u003c/p\u003e\n\n---\n \n## About\nThis is a react-native library for tracing close contact between 2 mobile devices by exchanging ephemeral tokens over BLE (Bluetooth Low Energy).  \n\nThe library will do the following:\n\n1. Advertise message with specific _service_uuid_ and generated _ephemeral token_\n2. Scan for for BLE signals with a specific _service_uuid_ and store the relevant scanned data into local device storage\n3. Provide simple API for JS to init these tasks in background and retrieve the scanned _tokens_\n4. Integrate with a module that will provide ephemerally encrypted tokens (might be optional part of the lib)\n\nThere is a chance this lib will be updated after Google \u0026 Apple will release the full [Contact Tracing API](https://www.apple.com/covid19/contacttracing/) solution.\n\n\n### Challanges\n1. iOS limitation of using ble while the app in the background - [link](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html) \n2. Estimate the distance between 2 devices without violating user's privacy, using the data we can send over the ble\n\n\n## Working plan\n\n Functionality | Android | iOS | \n:------------ | :-------------| :-------------| \nScan in foreground | :white_check_mark: |  :white_check_mark: |\nAdvertise in foreground | :white_check_mark: |  :white_check_mark: |\nScan in background | :white_check_mark: | TODO |\nAdvertise in background | :white_check_mark: | TODO |\nSave scanned data into local DB | :white_check_mark: | :white_check_mark: |\nReturn scanned data to JS | :white_check_mark: | :white_check_mark: | \nPass scannng \u0026 advertising configuration from JS (intervals..) | :white_check_mark: | :white_check_mark: |\nIntegration with tokens provider  |TODO|TODO|\nTests  |TODO|TODO|]\nFeatures for rssi calibration (GPS, Proximity)  |WIP|TODO|\n---\n\n\n## Getting started\n\n### Example Project \n\nThe Example project can be used as a reference of how to use the rn-contact-tracing API and as a helpful tool to fine-tune the scanning/advertising configuration\n\n\u003cimg align=\"right\" width=\"200\"  src=\"docs/example.gif\"\u003e\n\n### How to run the example project\n```properties\nnpm install\ncd example/ios\npod install\nFor Android - npm run android \nFor iOS - npm run ios\n``` \nIn Android - Click on Request Location Permission button\n\n### Installation\n`yarn add rn-contact-tracing`\n\nor\n\n`npm install rn-contact-tracing --save`\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e Android - Steps to manually link the library\u003c/strong\u003e\u003c/summary\u003e\n   \n#### `android/settings.gradle`\n```groovy\ninclude ':rn-contact-tracing'\nproject(':rn-contact-tracing').projectDir = new File(rootProject.projectDir, '../node_modules/rn-contact-tracing/lib/android')\n```\n\n#### `android/app/build.gradle`\n```groovy\ndependencies {\n   ...\n   implementation project(\":rn-contact-tracing\")\n}\n```\n\n#### `android/app/src/main/.../MainApplication.java`\nOn top, where imports are:\n\n```java\n    import moh.gov.il.specialble.SpecialBlePackage;\n```\n\nAdd the `RNLocationPackage` class to your list of exported packages.\n\n```java\n@Override\nprotected List\u003cReactPackage\u003e getPackages() {\n    return Arrays.asList(\n            List\u003cReactPackage\u003e packages = new PackageList(this).getPackages();\n            ...\n            packages.add(new SpecialBlePackage());\n            ...\n    );\n}\n```\n\u003c/details\u003e\n\n\n\n### Supported Platforms\n* iOS 10+\n* Android API 21+\n\n\n## Methods\n\n### Summary\n\n* [`setConfig`](#setconfigconfig)\n* [`getConfig`](#getconfigcallback)\n* [`startBLEService`](#startbleserviceconfig)\n* [`stopBLEService`](#stopbleservice)\n* [`startBLEScan`](#startblescanconfig)\n* [`stopBLEScan`](#stopblescan)\n* [`startBLEAdvertise`](#advertiseconfig)\n* [`stopAdvertise`](#stopadvertise)\n* [`getScansByKey`](#getscansbykeypubkey)\n* [`getAllDevices`](#getalldevices)\n* [`exportAllScansCsv`](#exportallscanscsv)\n* [`exportAllDevicesCsv`](#exportalldevicescsv)\n* [`cleanDevicesDB`](#cleandevicesdb)\n* [`cleanScansDB`](#cleanscansdb)\n\n\n---\n\n\n### Details\n\n#### `setConfig(config)`\n\n```javascript\n   SpecialBle.setConfig(config);\n```\n\nSets configuration options that will be used in scanning \u0026 advertising tasks.\n\n**Parameters:**\n\n| Name   | Type   | Required | Description |\n| ------ | ------ | -------- | ----------- |\n| config | object | Yes      | See below.  |\n\nSupported options:\n\n* `serviceUUID` - the ServiceUUID which identify the BLE broadcast you are going to advertise and scan for.\n* `scanDuration` -  scanning duration in milisec\n* `scanInterval` - the time in milisec between every scan\n* `advertiseDuration` - advertising duration in milisec (up to 180000ms)\n* `advertiseInterval` - the time in milisec between every advertising\n* `token` -  temporary token to advertise (for testing)\n\nFor Android\n* `advertiseTXPowerLevel` - advertise TX power level [docs](https://developer.android.com/reference/android/bluetooth/le/AdvertiseSettings.Builder#setTxPowerLevel(int))\n* `scanMatchMode` - match mode for Bluetooth LE scan filters hardware match [docs](https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder#setMatchMode(int))\n* `notificationTitle` - the title of the foreground service notification\n* `notificationContent` - the content of the foreground service notification\n\n---\n\n\n#### `getConfig(callback)`\n\n```javascript\n   SpecialBle.getConfig((config) =\u003e {\n    ....\n   })\n```\n\nGets the scanning \u0026 advertising configuration options that are currently defined in the library\n\n---\n\n#### `startBLEService(config)`\n\n```javascript\nSpecialBle.startBLEService(config);\n```\n\nStarts BLE background task scanning for a specific  - config is optional\n\n---\n\n#### `stopBLEService()`\n\n```javascript\nSpecialBle.stopBLEService();\n```\n\nStops the background service and all the tasks the service executing\n\n---\n\n#### `startBLEScan(config)`\n\n```javascript\nSpecialBle.startBLEScan(config);\n```\n\nStarts BLE scanning in foreground - config is optional\n\n---\n\n#### `stopBLEScan()`\n\n```javascript\nSpecialBle.stopBLEScan();\n```\n\nStarts BLE scanning \n\n---\n\n#### `advertise(config)`\n\n```javascript\nSpecialBle.advertise(config);\n```\n\nStarts BLE advertising in foreground - config is optional\n\n---\n\n#### `stopAdvertise()`\n\n```javascript\nSpecialBle.stopAdvertise();\n```\n\nStops BLE advertising \n\n---\n\n\n#### `getScansByKey(token, callback)`\n\n```javascript\n SpecialBle.getScansByKey(token, (scans) =\u003e {\n    ...\n })\n```\nGet list of scans events for a specific token, each object contains:\n* `scan_id` - unique id\n* `scan_timestamp` - epoch time of the scan event in \n* `public_key` - token key\n* `scan_address` - scaned device address\n* `scan_rssi` - rssi strength\n* `scan_tx` - tx strength\n* `scan_protocol` - the protocol used to scan the data (currently GAP/GATT)\n\n---\n\n#### `getAllDevices()`\n\n```javascript\n SpecialBle.getAllDevices((devices) =\u003e {\n       setDevices(devices)\n   })\n```\nGet list of unique devices that were scanned, each object contains:\n\n\n* `device_first_timestamp` - epoch time of the first scan event\n* `device_last_timestamp` - epoch time of the last scan event\n* `public_key` - token key\n* `device_address` - scaned device address\n* `device_rssi` - rssi strongest value\n* `device_tx` - tx strongest value\n* `device_protocol` - the protocol used to scan the data (currently GAP/GATT)\n\n---\n\n#### `exportAllScansCsv()`\n\n```javascript\n SpecialBle.exportAllScansCsv();\n```\nExport the full Scans events DB to csv file\n\n---\n\n\n#### `exportAllDevicesCsv()`\n\n```javascript\nSpecialBle.exportAllDevicesCsv();\n```\nExport the full Devices DB to csv file\n\n---\n\n\n#### `cleanDevicesDB()`\n\n```javascript\nSpecialBle.cleanDevicesDB();\n```\nClear all scanned devices\n\n---\n\n#### `cleanScansDB()`\n\n```javascript\nSpecialBle.cleanScansDB();\n```\nClear all scans\n\n---\n\n#### Events from Native to JS\n- `scanningStatus` - event can be true/false\n- `advertisingStatus` - event can be  true/false\n- `foundDevice` - event has 2 params: {event.device_name, event.device_address}\n- `error` - {event.error_message}\n\n---\n\n### Why did we build this lib?\nDue to COVID-19 pandemic, several groups and health authorities released apps that will help to identify and notify people that are at risk of exposure.\n\nSome of these apps are written with RN and based on tracking user location which is not enough such as [Hamagen](https://github.com/MohGovIL/hamagen-react-native), and they willing to add BLE based functionality.  \n\nThere are lots of great libs that expose ble functionality for RN, i.e [react-native-ble-plx](https://github.com/Polidea/react-native-ble-plx) \u0026 [react-native-ble-manager](https://github.com/innoveit/react-native-ble-manager) but we wanted reduce the amount of dependancies as much as possible and exectue very specfic BLE functionality in background.\n\nIn addition, we looked at several great apps written for the same purpose in native, but each one of them is not written in a way that we could use as a stand-alone library. \n[OpenTrace](https://github.com/opentrace-community)) - includes the full business logic (UI..) that we don't want to use. \n[DP^3T Project](https://github.com/DP-3T) - include cryptography logic that we prefer to replace\n\n##### Privacy (what do we advertise and save to DB)\nTBD\n \n\n\n### References\n* https://github.com/opentrace-community\n* ....\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMohGovIL%2Frn-contact-tracing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMohGovIL%2Frn-contact-tracing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMohGovIL%2Frn-contact-tracing/lists"}