Android

Native Android toolkit that integrates the Zing Fitness experience into your app. The SDK ships as an AAR (coach.zing:fitness-sdk) consumable via GitHub Packages.

Requirements

Requirement	Value / Notes
Minimum Android version	8.0 (API 26)
Compile SDK	34+
Kotlin	2.1.0
Dependency injection	Hilt (`com.google.dagger:hilt-android`)
Maven credentials	GitHub Packages PAT with `read:packages`

Setup

Add the GitHub Packages Repository

Add the following to your settings.gradle or top-level build.gradle:


// settings.gradle or top-level build.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/Muze-Fitness/fitness-coach-sdk-android")
 
            val localProperties = java.util.Properties()
            val file = File(rootDir, "local.properties")
            if (file.exists()) {
                localProperties.load(file.inputStream())
            }
 
            credentials {
                username = localProperties.getProperty("sdk_maven_read_username")
                    ?: System.getenv("GITHUB_USER")
                password = localProperties.getProperty("sdk_maven_read_token")
                    ?: System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

Create local.properties next to your top-level settings.gradle if it does not exist yet and provide the credentials:


sdk_maven_read_username=GITHUB_USERNAME
sdk_maven_read_token=ghp_xxx_with_read_packages

Declare the Dependency


dependencies {
    implementation("coach.zing:fitness-sdk:<latest-version>")
}

Replace <latest-version> with the version published in GitHub Packages (e.g. 1.0.5).

Enable Hilt

Add the Hilt plugin and dependencies to your app-level build.gradle:


plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.dagger.hilt.android")
    kotlin("kapt") // or id("com.google.devtools.ksp")
}
 
dependencies {
    implementation("com.google.dagger:hilt-android:2.56.1")
    kapt("com.google.dagger:hilt-android-compiler:2.56.1")
    // ksp("com.google.dagger:hilt-android-compiler:2.56.1")
}

Create an Application Subclass

Create an Application subclass that extends SdkApplication:


@HiltAndroidApp
class FitnessApp : SdkApplication()


<application
    android:name=".FitnessApp"
    ... />

Initialization & Authentication

The SDK follows a three-step lifecycle: init() → login() → logout().

init(sdkAuth) — configure the authentication method (call once).
login() — start a session (must be called after init only when session is not logged in — check SdkAuthState.LoggedOut).
logout() — end the session and clear user data.

Authentication methods

Method	Class	Description
Partner Key	`SdkAuthentication.ApiKey`	Simple API key authentication
Partner Token	`SdkAuthentication.ExternalToken`	Token-based auth with partner’s own backend

Initialization

Partner Key — pass your API key directly:


ZingSdk.init(SdkAuthentication.ApiKey(apiKey = "your-api-key"))

Partner Token — implement AuthTokenCallback to provide and refresh tokens:


ZingSdk.init(
    SdkAuthentication.ExternalToken(
        authTokenCallback = object : AuthTokenCallback {
            override suspend fun getAuthToken(): String {
                return yourAuthRepo.getToken()
            }
 
            override fun onTokenInvalid() {
                // handle invalid token, e.g. refresh or re-authenticate
            }
        }
    )
)

Note: getAuthToken() is a suspend function called by the SDK whenever it needs a valid token. onTokenInvalid() is called when the current token is rejected.


suspend fun login()

Must be called after init() when authState is SdkAuthState.LoggedOut. Throws SdkAlreadyLoggedInException if the user is already logged in.

Auth state monitoring

Observe ZingSdk.authState: StateFlow<SdkAuthState> to react to authentication changes:

State	Description
`SdkAuthState.LoggedOut`	No active session
`SdkAuthState.InProgress`	Login is in progress
`SdkAuthState.Authenticated`	Session active

Logout


suspend fun logout()

Ends the current session. Throws SdkAlreadyLoggedOutException if the user is already logged out.

Full example


class FitnessApp : SdkApplication() {
    override fun onCreate() {
        super.onCreate()
        ZingSdk.init(SdkAuthentication.ApiKey(apiKey = "your-api-key"))
    }
}
 
// Start a session (e.g. in your Activity or ViewModel)
fun onStart(scope: CoroutineScope) {
    scope.launch {
        if (ZingSdk.authState.value is SdkAuthState.LoggedOut) {
            ZingSdk.login()
        }
    }
}
 
// End the session
fun onLogout(scope: CoroutineScope) {
    scope.launch {
        ZingSdk.logout()
        // e.g. navigate to login or clear user data
    }
}

Theming

Working with themes

Use the theming playground to interactively preview how colors, typography, corner rounding, and images look in the SDK screens before writing any code.

Pass a ZingSdkTheme to ZingSdk.init() to customize the SDK’s appearance. Every field is optional — any unset field falls back to the SDK default.


ZingSdk.init(
    sdkAuth = ...,
    theme = ZingSdkTheme(
        colors = ZingSdkTheme.Colors(
            brandPrimary = 0xFF1A73E8,
            brandSecondary = 0xFF34A853,
        ),
        cornersRounding = ZingSdkTheme.CornerRadius(
            button = ZingSdkTheme.CornerRadius.SdkRadius.Pill,
        ),
        typography = ZingSdkTheme.Typography(
            brand = Typeface.createFromAsset(assets, "fonts/MyBrandFont.ttf"),
            system = Typeface.createFromAsset(assets, "fonts/MySystemFont.ttf"),
        ),
        assets = ZingSdkTheme.Assets(
            planBackground = R.drawable.my_plan_background,
            welcomePicture = R.drawable.my_welcome_picture,
            coachImages = ZingSdkTheme.Assets.CoachAsset(
                john = R.drawable.my_coach_john,
                jennifer = R.drawable.my_coach_jennifer,
                sarah = R.drawable.my_coach_sarah,
                chris = R.drawable.my_coach_chris,
            ),
        ),
    ),
)

Field	Type	Description
`colors`	`ZingSdkTheme.Colors`	Overrides brand, text, button, and background colors. Values are `Long` in AARRGGBB format.
`cornersRounding`	`ZingSdkTheme.CornerRadius`	Overrides button border radius. Use `SdkRadius.Value(dp)` for a fixed radius or `SdkRadius.Pill` for a pill shape.
`typography`	`ZingSdkTheme.Typography`	Overrides font typefaces for brand and system text.
`assets`	`ZingSdkTheme.Assets`	Overrides images for plan background, welcome screen, and coach portraits.

Working with typography

Pass Typeface objects directly to ZingSdkTheme.Typography.

Field	Applies to	Default
`brand`	Headings, display text, counter, coach name	SDK built-in (Outfit)
`system`	Body text, UI elements, coach chat	SDK built-in (Roboto)

Both fields are optional — omitting a field keeps the SDK’s built-in font for that role.

Working with pictures

Pass drawable resource IDs directly to ZingSdkTheme.Assets. The SDK uses the IDs to load images from your app’s resources.

Field	Used for
`planBackground`	Plan section background image
`welcomePicture`	Welcome screen illustration
`coachImages.john`	Coach John avatar
`coachImages.jennifer`	Coach Jennifer avatar
`coachImages.sarah`	Coach Sarah avatar
`coachImages.chris`	Coach Chris avatar

All fields are optional — omitting a field falls back to the SDK’s built-in image.

For best quality across device densities, provide density-specific variants. Android automatically picks the correct one:


res/
  drawable-mdpi/my_welcome_picture.png
  drawable-hdpi/my_welcome_picture.png
  drawable-xhdpi/my_welcome_picture.png
  drawable-xxhdpi/my_welcome_picture.png
  drawable-xxxhdpi/my_welcome_picture.png

Launching Zing Screens

You can open any major Zing screen explicitly via ZingSdkActivity.launch(context, StartingRoute.<Destination>). Supported destinations include:

StartingRoute.Home
StartingRoute.CustomWorkout
StartingRoute.AiAssistant
StartingRoute.WorkoutPlanDetails
StartingRoute.FullSchedule
StartingRoute.ProfileSettings

Example


button.setOnClickListener {
    ZingSdkActivity.launch(this, StartingRoute.AiAssistant)
}