Concepts of the SDKs

An SDK is the library an app embeds to send reports to the Heardfix back office. This page holds what the SDKs share, and says so when a section applies to one SDK only. Each SDK guide only covers its own code.

The app and its key

OwnWeb creates your app in your organization. Its page, under Heardfix, Apps, shows:

• the key: hf_ followed by 32 letters and digits. It identifies the app and ships inside it, so it is public, like a Sentry DSN. It does not authenticate the app: App Check does, except with the key only method;
• the initialisation of the Flutter SDK for a mobile app, and the script tag of the web module for a website, prefilled with the key, ready to copy.

The endpoint

The endpoint is the address of the back office. The SDKs send to the back office hosted by OwnWeb by default: the initialisation on the app page only gives an endpoint on a back office of your own. The SDK sends each report to {endpoint}/api/heardfix/v1/reports. The request is described in the API contract.

Authentication: Firebase App Check

The back office only accepts a report from a mobile app that proves it comes from your app, through Firebase App Check: Play Integrity on Android, App Attest or DeviceCheck on iOS. A mobile app without Firebase uses the key only method instead. A website authenticates by its allowed origins and a proof of work instead, see the web module.

The SDK has no authentication logic. Your app gives it a callback that returns a fresh App Check token, called before each upload, and the SDK sends it as X-Firebase-AppCheck.

1. In the Firebase console, add your iOS and Android apps to a Firebase project, then register them in App Check: Play Integrity for Android, App Attest for iOS.
2. Copy the Firebase project number from the project settings (the number, not the project id). An admin of your organization enters it on the app page, field "Firebase project number". The back office only accepts tokens issued for this project.
3. Activate App Check in the app before initialising the SDK, as the SDK guide shows.

Develop against the back office

There is one back office: the one your users send to. To send reports from a simulator or a debug build, use the App Check debug provider:

1. Activate the debug provider in debug builds only. Release builds keep Play Integrity and App Attest.
2. Run the app once. The Firebase SDK prints a debug token in the console (on iOS, add -FIRDebugEnabled to the launch arguments of the Xcode scheme).
3. In the Firebase console, App Check, Apps, "Manage debug tokens", add this token.

Reports from this simulator are now accepted. A debug token lets anyone pass App Check: keep it out of the repository, and delete it from the Firebase console once it is no longer used.

Authentication: key only

A mobile app without Firebase sends its key alone, as Sentry does with its DSN. An admin of your organization enables the key_only method on the app page, and the app passes no App Check token: the initialisation on the app page has none.

The key ships inside the app, so anyone who extracts it can send reports in your app's name, from a script or a forged app. The back office contains it rather than prevents it:

• the rate limits, 5 reports per hour per installation and 20 per IP;
• a daily report limit for the app, 100 unless OwnWeb sets another. Beyond it, reports wait on the device until midnight, time zone of the back office, then leave on their own;
• the regeneration of the key by OwnWeb, when it is abused. The old key is refused at once: the versions of the app that carry it can no longer send, and keep their reports until an update brings the new key. Copy the new key from the app page and publish an update.

Choose App Check when your app already has Firebase: it proves each report comes from your genuine app.

Kinds

A report is a bug report (bug, the user reports a problem) or a suggestion (feature, the user suggests an improvement). Give the user two entries, one per kind. A triager may change the kind once the report is received. Terms are defined in the glossary.

What a report carries

The table describes a report of the Flutter SDK. The web module sends the page address, the browser and the window size instead of the battery, memory and storage, and the JavaScript errors of the page instead of the log and the Sentry ids: see the web module.

Every field and its limits are listed in the API contract. Every SDK shows the user what it sends before they send it.

The content of a report is health data: it stays in the back office, which needs an HDS certified host to store health data. Never log personal or health data: no email, no name, no measurement, no text typed by the user. See data protection.

Offline and retries

The web module keeps no queue: it sends the report once and tells the visitor when it fails. In the Flutter SDK, a report is stored on the device as soon as the user sends it, then uploaded. The answer of the back office decides what happens next:

The report id is sent as Idempotency-Key: a report sent twice after a lost answer is stored once.

Limits

• Mobile apps: 5 reports per hour per installation, 20 per hour per IP address. Websites: 60 per hour per IP address, since the web module sends a new installation id with each report. Beyond, the back office answers 429.
• 3 images per report, 10 MB each.