https://github.com/hyperjumptech/hypertrace-android-sdk

Kotlin implementation of OpenTrace by Hyperjump
https://github.com/hyperjumptech/hypertrace-android-sdk

Last synced: 11 months ago
JSON representation

Kotlin implementation of OpenTrace by Hyperjump

Host: GitHub
URL: https://github.com/hyperjumptech/hypertrace-android-sdk
Owner: hyperjumptech
License: gpl-3.0
Created: 2022-01-07T04:10:04.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2022-04-11T08:43:06.000Z (about 4 years ago)
Last Synced: 2025-03-13T10:17:13.650Z (about 1 year ago)
Language: Kotlin
Size: 957 KB
Stars: 2
Watchers: 6
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE.md

Awesome Lists containing this project

README

# Android Hypertrace - Kotlin implementation of OpenTrace by Hyperjump

Kotlin OpenTrace implementation based on [BlueTrace specification](https://bluetrace.io/static/bluetrace_whitepaper-938063656596c104632def383eb33b3c.pdf). Example app is available in [example module](https://github.com/hyperjumptech/hypertrace-android-sdk/tree/main/example/src/main).

### Table of Content

- [Requirements](#requirements)
- [Installation](#installation)
- [Run the tests](#run-the-tests)
- [How to use](#how-to-use)
- [Compatibility with Hypertrace iOS SDK](#compatibility-with-hypertrace-ios-sdk)
- [Debugging](#debugging)
- [Troubleshooting](#troubleshooting)
- [Protocol version](#protocol-version)
- [Security enhancement](#security-enhancements)
- [Statement from Google](#statement-from-google)
- [Changelog](#changelog)

### Requirements

- Android API level 23+ (Android M)
- Kotlin 1.5.31
- A device with Bluetooth Low Energy (BLE) support.
- This SDK requires the application be granted following permissions:
- `android.permission.ACCESS_FINE_LOCATION`
- `android.permission.ACCESS_COARSE_LOCATION`
- `android.permission.BLUETOOTH`
- A running implementation of [Hypertrace server](https://github.com/hyperjumptech/hypertrace).

### Installation

1. Add jitpack repository to your project's `build.gradle` file

```
allprojects {
repositories {
maven { url "https://jitpack.io" }
}
}
```

2. Add Hypertrace to your dependencies, change `x.y.z` below to version in the [release page](https://github.com/hyperjumptech/hypertrace-android-sdk/releases).

```
dependencies {
implementation 'com.github.hyperjumptech:hypertrace-android-sdk:x.y.z'
}
```

### Running tests

The current state of the project only has instrumented tests. To run it, you need a connected android emulator or device and run the command below.

```
./gradlew hypertrace:connectedDebugAndroidTest --stacktrace
```

### How to use

#### Start background service

```kotlin
val config = HypertraceSdk.Config()
HypertraceSdk.startService(config)
```

##### Available configuration

#### Stop background service

`stopService` will stop Hypertrace background service.

```kotlin
HypertraceSdk.stopService()
```

#### Get handshake PIN

`getHandshakePin` will fetch a PIN from server for identification from authority.

**Return**: String, handshake PIN.

**Throw**: Exception on failures.

```kotlin
HypertraceSdk.getHandshakePin()
```

#### Upload contact encounter

`uploadEncounterRecords` will upload recorded BLE encounters in local to server.

**Return**: Unit / void.

**Throw**: Exception on failures.

Params:

- secret: temporary password provided by authority.

```kotlin
HypertraceSdk.uploadEncounterRecords(secret, onSuccess = {}, onError = {})
```

#### Count encounter

`countEncounters` will return encounter record count. By default, this method only count the expired records, respective to **recordTTL**. See [configuration](#available-configuration).
**Param**: `before`, timestamp in millis.
**Return**: Record count before given timestamp, **recordTTL** by default.

#### Remove encounter

`removeEncounters` will delete encounter records. By default, this method only delete expired records, respective to **recordTTL**. See [configuration](#available-configuration).

**Param**: `before`, timestamp in millis.
**Return**: Unit / void.

### Compatibility with Hypertrace iOS SDK

For compatibility with [Hypertrace iOS SDK](https://github.com/hyperjump/hypertrace-ios-sdk), `bleServiceUuid` and `bleCharacteristicUuid` must be identical to their corresponding iOS configuration.

### Debugging

Hypertrace SDK provides the following classes for debugging purposes:

- `tech.hyperjump.hypertrace.scandebug.ScanDebugActivity` for bluetooth scanning status.
- `tech.hyperjump.hypertrace.scandebug.StreetPassDebugActivity` for contact tracing records in local.

### Troubleshooting

- Foreground service get killed when app is paused on device model XXX.

For non-AOSP users, you need to whitelist the application from OS' power manager. For further information, please refer to [Don't Kill My App](https://dontkillmyapp.com/) website.

### Protocol Version

Protocol version used should be 2 (or above)
Version 1 of the protocol has been deprecated

---

### Security Enhancements

Hypertrace uses [OkHttp v4.x](https://square.github.io/okhttp/) under the hood. We provide configurable certificate pinner, for implementation, refer to [CertificatePinner documentation.](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-certificate-pinner/)

---

### Statement from Google

The following is a statement from Google:
"At Google Play we take our responsibility to provide accurate and relevant information for our users very seriously. For that reason, we are currently only approving apps that reference COVID-19 or related terms in their store listing if the app is published, commissioned, or authorized by an official government entity or public health organization, and the app does not contain any monetization mechanisms such as ads, in-app products, or in-app donations. This includes references in places such as the app title, description, release notes, or screenshots.
For more information visit [https://android-developers.googleblog.com/2020/04/google-play-updates-and-information.html](https://android-developers.googleblog.com/2020/04/google-play-updates-and-information.html)"

---

### ChangeLog

**0.9.0**

- First release.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/hyperjumptech/hypertrace-android-sdk

Awesome Lists containing this project

README