Install the SDK

We host our SDK using Github Packages, which are synced using Gradle. These instructions how you how to link to the repository and sync.

Create a Github Access Token

1. Create an account at Github if you do not have one, otherwise sign in.

2. Open the Settings / Developer Settings page.

3. Click on the Personal Access tokens heading in the side bar, and select Tokens (classic) in the list which appears.

4. Click on the Generate new token button, and select Generate new token (classic).

   1. Give the token a name in the Note field, such as FlightRecorder Package Access.

   2. Set the Expiration to something long lasting. You will need to generate a new token when this expires to continue to access the Flight Recorder Github Pacakge.

   3. In the Select Scopes section, check the box next to read:packages, underneath the write:packages checkbox.

5. Click on Generate token.

6. Copy the access token which appears and save it somewhere.

Add the Github Access Token to your Project

1. Open your Android project inside Android Studio.

2. Switch to the Project Files view in Android Studio if you are not already in that view. To do this, locate the dropdown at the top of the projects window, click on the currently selected option (e.g., Android), and from the dropdown menu, choose Project Files.

3. In the menu bar, select File -> New -> File

4. Enter github.properties into the Name field of the New File popup.

5. Press Enter. If you are asked if you want to add the file to git, select Cancel.

6. The file will appear in the Project Files view at the root. Click on the file to open it, if it is not already open.

7. Enter the following text into the file, replacing GITHUB_USERNAME with your Github username, and ACCESS_TOKEN with your Access Token you just copied:

   github.properties

   username=GITHUB_USERNAME
   token=ACCESS_TOKEN

8. Save the file.

9. To ensure you do not add the github.properties file into your version control managment system, add github.properties to the ignore file. For Git, this would be:

   1. In the Project Files view, open the .gitignore file.

   2. Add the following line to .gitignore: github.properties

Declare the Repository in Gradle

First, you need to work out where you are already referencing your repositories. There are a few places this could be. If you already know, skip to the relevant section:

• If you declare your repositories in the project Gradle file: Project Gradle File
• If you declare your repositories in the app module or single module: Module Gradle File
• If you declare your repositories centrally in the settings: Settings Gradle File

Project Gradle File

1. Open the build.gradle.kts (Kotlin DSL) or build.gradle (Groovy DSL) file for your project. This is located at the root of your project in the Project view. In the Android view this is labelled with (Project: ... ).

2. In the root of the file, search for the following block:

   Kotlin / Groovy

   allprojects {
       repositories {
           ...
       }
   }

   Ignore the repositories block inside of the buildscript block, this is for build plugins only. If you do not find the allprojects -> repositories block in the project Gradle file, move on to Module Gradle File. If you found the repositories block in the Gradle file continue here.
3. Add the following import statement to the top of the file: import java.util.Properties

4. Insert the highlighted code below in the repositories block:

   Kotlin: build.gradle.kts

   repositories {
     ...
     maven {
       val propsFile = rootProject.file("github.properties")
       val props = Properties()
       props.load(propsFile.inputStream())
       url = uri("https://maven.pkg.github.com/pulselabs-ai/flight-recorder-android-package")
       credentials {
           username = props.getProperty("username")
           password = props.getProperty("token")
       }
     }
   }

   Groovy: build.gradle

   repositories {
     ...
     maven {
       def propsFile = rootProject.file('github.properties')
       def props = new Properties()
       props.load(new FileInputStream(propsFile))
       url = "https://maven.pkg.github.com/pulselabs-ai/flight-recorder-android-package"
       credentials {
         username props['username']
         password props['token']
       }
     }
   }

5. You should be prompted to sync Gradle by Android Studio. Click the sync now link.

6. Move on to the section Declare the Dependency in Gradle.

Module Gradle File

1. Open the build.gradle.kts (Kotlin DSL) or build.gradle (Groovy DSL) file for your app module. The file is typically located in the root directory of the app module, at {APP_MODULE_FOLDER}.

2. Locate the android block in the build.gradle(.kts) file, and then search for the repositories block in there. The repositories block may be nested within an allprojects block as shown in the example below:

   Kotlin / Groovy

   allprojects {
       repositories {
           ...
       }
   }

   If you do not find the repositories block in the module level Gradle file, move on to the next section, Settings Gradle File. If you found the repositories block in the Gradle file continue here.
3. Add the following import statement to the top of the file: import java.util.Properties

4. insert the highlighted code below in the repositories block:

   Kotlin: build.gradle.kts

   repositories {
     ...
     maven {
       val propsFile = rootProject.file("github.properties")
       val props = Properties()
       props.load(propsFile.inputStream())
       url = uri("https://maven.pkg.github.com/pulselabs-ai/flight-recorder-android-package")
       credentials {
           username = props.getProperty("username")
           password = props.getProperty("token")
       }
     }
   }

   Groovy: build.gradle

   repositories {
     ...
     maven {
       def propsFile = rootProject.file('github.properties')
       def props = new Properties()
       props.load(new FileInputStream(propsFile))
       url = "https://maven.pkg.github.com/pulselabs-ai/flight-recorder-android-package"
       credentials {
         username props['username']
         password props['token']
       }
     }
   }

5. You should be prompted to sync Gradle by Android Studio. Click the sync now link.

6. Move on to the section Declare the Dependency in Gradle.

Settings Gradle File

1. Open the settings.gradle.kts (Kotlin DSL) or settings.gradle (Groovy DSL) file for the project. This file should be located in the root directory of the project.

2. Locate the repositories block inside of the dependencyResolutionManagement block. If no repositories block exists, then you have no repositories declared yet in your project. Go back to the section Check the project level Gradle file and create the blocks described in there in order to cover the widest range of circumstances and architectures. If you found the repositories block in the Gradle file continue here.
3. If you are using Kotlin for your Gradle file (settings.gradle.kts), add the following import statement to the top of the file: import java.util.Properties.

4. Insert the highlighted code below in the repositories block:

   Kotlin: settings.gradle.kts

   dependencyResolutionManagement {
       ...
       repositories {
           ...
           maven {
             val propsFile = File(rootProject.projectDir, "github.properties")
             val props = Properties()
             props.load(propsFile.inputStream())
             url = uri("https://maven.pkg.github.com/pulselabs-ai/flight-recorder-android-package")
             credentials {
                 username = props.getProperty("username")
                 password = props.getProperty("token")
             }
           }
       }
   }

   Groovy: build.gradle

   dependencyResolutionManagement {
     ...
     repositories {
       ...
       maven {
         def propsFile = new File(rootProject.projectDir, 'github.properties')
         def props = new Properties()
         props.load(new FileInputStream(propsFile))
         url = "https://maven.pkg.github.com/pulselabs-ai/flight-recorder-android-package"
         credentials {
           username = props.getProperty("username")
           password = props.getProperty("token")
         }
       }
     }
   }

5. You should be prompted to sync Gradle by Android Studio. Click the sync now link.

Declare the Dependency in Gradle

1. Open the build.gradle.kts (Kotlin DSL) or build.gradle (Groovy DSL) file for your app module. The file is typically located in the root directory of the app module, at {APP_MODULE_FOLDER}.

2. Locate the dependencies block in the build.gradle(.kts) file.

3. Insert the implementation declaration highlighted below somewhere inside the dependencies block.

   Kotlin: build.gradle.kts

   dependencies {
       ... 
       implementation("androidx.compose.material3:material3")
       implementation("ai.pulselabs:flightrecorder:1.+")

   Groovy: build.gradle

   dependencies {
       ... 
       implementation 'androidx.compose.material3:material3'
       implementation 'ai.pulselabs:flightrecorder:1.+'

   We follow Semantic Versioning 2.0.0, which means we will add bugfixes to the patch version (x.x.x), new features with no breaking changes to the minor version (x.x.x) and will always increase the major version (x.x.x) for breaking changes.

   The example above will keep you on the current major version until you change the gradle file. If you prefer, you can modify the version to stick to the latest minor: 1.0+, or fix to the current version, visible at https://flightrecorder.pulselabs.ai/download-sdk.
4. We allow passing in your own Typography object (optional) which will be used to create our composable views.

5. You should be prompted to sync Gradle by Android Studio. Click the sync now link.

The SDK has now been installed into your application.

Update R8 Configuration

1. Switch to the Project view in Android Studio if you are not already in that view.

2. Open the folder app, or equivalent for your project, and the file proguard-rules.pro. If the file does not exist, create it.

3. Add the following to the file:

   proguard-rules.pro

   -dontwarn android.app.Activity$ScreenCaptureCallback

Transitive Dependency Checks

FlightRecorder uses a small number of androidx dependencies. This may impact your application if you use the same dependences, as Gradle will select the latest version in the event two versions are provided, one in the app gradle, and the other by our SDK. In this section we explain how to validate the dependencies and make any necessary updates.

Jetpack Compose

Check the gradle file containing the dependencies block, and look inside that block for references for the following libraries:

• androidx.compose.... this indicates that your project is using Jetpack Compose.
• androidx.compose.material3:... this indicates that your project is using material3.
• androidx.compose:compose-bom:... this indicates that your project is using the Jetpack Compose Bill Of Materials (BOM) to centrally manage the versions of the Jetpack Compose libraries.

If you use the Jetpack Compose BOM, check the version.

• If the version is lower than version 2024.06.00, then your application will be updated to use 2024.06.00 upon installation of FlightRecorder. Update the version to 2024.06.00 or later, and run thorough testing. If you cannot upgrade, and you use material3, you cannot use the SDK at this time.

• If the version is 2024.06.00 or higher, no changes are required. Our SDK has been tested with more recent versions and you can proceed to the next steps.

If you manually specify the version of androidx.compose.material3:

• If the version is lower than 1.2.1, you must update it to 1.2.1 or higher. If you cannot do this, you cannot use the SDK at this time.

An additional couple of steps are required if you do not use the Jetpack Compose BOM:

1. Check that the versions of the libraries starting with androidx.compose all match the versions of a particular BOM, ensuring they all work together as expected. For example, if you use androidx.compose.animation:animation and androidx.compose.material3:material3, and androidx.compose.animation:animation is using version 1.6.3, then you should also use androidx.compose.material3:material3 version 1.2.1, because those are defined as compatible in BOM 2024.06.00. If you need to use different versions of the libraries, test the SDK carefully. You may find some issues or the app may crash, due to backwards incompatible changes in androidx and these will be resolved by ensuring the versions are compatible.
2. Add the following libraries explicitly to the gradle file, with the relevant versions from the BOM that matches the versions of the libraries you are using. For example, if you use androidx.compose.animation:animation 1.6.3, then you should use the versions from BOM 2024.06.00.

• androidx.compose.ui:ui

• androidx.compose.ui:ui-graphics

• androidx.compose.ui:ui-tooling-preview

• androidx.compose.material3:material3

Other Libraries

Check the gradle file containing the dependencies block, and look inside that block for references for the following libraries, and compare the version you use to the version we use:

• androidx.activity:activity-compose:1.7.0

• androidx.core:core-ktx:1.10.1

• androidx.lifecycle:lifecycle-runtime-ktx:2.6.1

• androidx.lifecycle:lifecycle-viewmodel-compose:2.6.1

If your application does not use any of these libraries, you can proceed.

If your application uses a higher version of all of these libraries, you can proceed. We test the SDK with more recent versions. However, if you encounter any issues when testing the SDK please notify us.

If your application uses a lower version of any of these libraries, and you do not force specific versions, your application will be using the version we specify once the SDK is installed. androidx changes should be backwards compatible, but there are cases where they are not. You have two options:

1. You could choose to update your gradle file to set a strict version as described here, this will force FlightRecorder to downgrade. You should first contact us and let us know the versions you will need to support, and we can test and validate for you.
2. You could choose to update the libraries at this time, and re-test your application as you would when updating any core libraries. Gradle will always choose the latest version, so you do not have to update your gradle file for this option, however it is recommended to explicitly specify the versions in your gradle file for clarity.