Installation

Prerequisites

• A Flutter app (3.29 or later, with Swift Package Manager support)
• A Mac with Xcode to build the iOS app (iOS builds are macOS-only)
• A GitHub account with access to the FizzUp GitHub Packages Maven repository, for Android

TIP

The package itself installs the same way on any OS. Only the iOS build (building for a device/simulator) requires macOS. You can develop and build the Android side on macOS, Linux, or Windows.

Install the package

The package is not published to pub.dev — it is a proprietary SDK distributed as a Git dependency from its public repository. Add it to your app's pubspec.yaml, pinning a release tag for reproducibility:

dependencies:
  trainingkit_flutter:
    git:
      url: https://github.com/getfizzup/trainingkit-flutter
      ref: v0.1.0

Equivalently, from the command line:

flutter pub add trainingkit_flutter \
  --git-url https://github.com/getfizzup/trainingkit-flutter \
  --git-ref v0.1.0

Why a Git dependency?

Flutter supports Git dependencies natively, including for plugins with native code. Since the repository is public, there is no need to publish to pub.dev (which is public-only and not suited to a licensed SDK). The native build — resolving the TrainingKit Swift package on iOS and the Android SDK from GitHub Packages — works exactly the same whether the package comes from Git or a local path.

During local package development, use a path dependency instead:

dependencies:
  trainingkit_flutter:
    path: ../relative/path/to/trainingkit-flutter

Then fetch packages:

flutter pub get

iOS setup

The iOS plugin is a Swift Package. It depends on the TrainingKit iOS SDK (getfizzup/trainingkit-ios-sdk), itself a Swift package whose TrainingKit product is a binary target (TrainingKit.xcframework). Swift Package Manager resolves and links it automatically — there is nothing to vendor, fetch, or configure in CocoaPods.

Enable Swift Package Manager

This plugin requires Flutter's Swift Package Manager support, enabled by default on Flutter 3.29+. If you previously turned it off, re-enable it:

flutter config --enable-swift-package-manager

The first iOS build resolves the TrainingKit package from GitHub, so it needs network access.

Deployment target

Set the iOS deployment target to 15.1 or higher in the Xcode project (Runner target → Build Settings → iOS Deployment Target, or IPHONEOS_DEPLOYMENT_TARGET in project.pbxproj). The plugin's Swift package declares iOS 15.1 as its minimum.

HealthKit usage descriptions

The classic workout flow requests HealthKit authorization. Add usage descriptions to ios/Runner/Info.plist, otherwise iOS terminates the app when a classic workout starts:

<key>NSHealthShareUsageDescription</key>
<string>Read workout and energy data to track your sessions.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>Save completed workouts to Apple Health.</string>

Android setup

The Android SDK is distributed through GitHub Packages. The package's android/build.gradle.kts already declares the FizzUp Maven repository, so in your app you only need to provide credentials and set the minimum SDK.

Providing credentials

Provide GitHub credentials in your app's android/local.properties:

GithubUser=your-github-username
GithubToken=your-github-token

Or through environment variables:

export GITHUB_USERNAME=your-github-username
export GITHUB_TOKEN=your-github-token

Minimum SDK

TrainingKit requires Android API level 24 or higher. Set minSdk in your app's android/app/build.gradle.kts:

defaultConfig {
    minSdk = 24
}

Internet and screen-on permissions

Add the following to your app's android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Build the app

After adding the dependency, rebuild the app. A hot reload is not sufficient after adding a native package.

flutter run