Install on Android

AFCore for Android is a Maven artifact published to GitHub Packages at AdvantaHealth/AFCore. It supports minSdk 26 and needs compileSdk 37 (Android 17), Android Gradle Plugin 9.0+ and JDK 17. Apps that target API 37 are supported.

1. Add the repository and the dependency

settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/AdvantaHealth/AFCore")
            credentials {
                username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GPR_USER")
                password = providers.gradleProperty("gpr.key").orNull ?: System.getenv("GPR_KEY")
            }
        }
    }
}

Put the credentials in ~/.gradle/gradle.properties (or CI environment variables), never in the repository:

gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_GITHUB_PAT   # token with read:packages scope

App module build.gradle.kts:

dependencies {
    implementation("com.advantahealth:core-android:1.12.1")
}

Newer versions are on the Releases page. Upgrading from 1.11? Read Upgrading to 1.12 first.

2. Initialize in your Application

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val config = AFCoreConfig.builder()
            .baseUrl("https://api.example.com")
            .realm(AFRealm.BISMUTH)          // AFRealm.HORIZON if your members are on Horizon
            .enableLogging(BuildConfig.DEBUG)
            .build()
        AFCore.initialize(config)
    }
}

Register the class with android:name=".MyApp" on your <application>. AFCore obtains the application context itself. See Initialization for the options.

3. Exclude AFCore from backups (required)

AFCore's session store is encrypted with a key that never leaves the device, and a restored session would belong to a member who is not signed in there. Android cannot merge a library's backup rules into your app, so unless your app sets android:allowBackup="false", reference AFCore's rule files:

AndroidManifest.xml

<application
    android:name=".MyApp"
    android:fullBackupContent="@xml/afcore_backup_rules"
    android:dataExtractionRules="@xml/afcore_data_extraction_rules"
    …>

If your app already has its own rule files, keep them and add AFCore's entries -- in fullBackupContent and in both the <cloud-backup> and <device-transfer> sections of dataExtractionRules:

<exclude domain="sharedpref" path="key_active_fit_core_prefs.xml" />
<exclude domain="sharedpref" path="af_boot_config.xml" />
<exclude domain="sharedpref" path="af_geofence_store.xml" />
<exclude domain="file" path="afcore_outbox_media/" />

When you upgrade AFCore, compare your copy with the shipped files in case an entry was added.

4. Feature setup

• Permissions -- AFCore's manifest declares the permissions its features may use (location, background location, activity recognition, camera, notifications, Health Connect) and they merge into your app. Remove the ones you do not need with tools:node="remove".

• SmartWalking reads steps from Health Connect, which routes its permission screens to an activity of your app. Add these intent filters to that activity -- see SmartWalking for the connect flow:

  <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
  </intent-filter>
  <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
  </intent-filter>

• Gym Visits uses background location: request it only after the member opts in, and declare it in the Play Console -- see Gym Visits.

• Push notifications -- see Push Notifications.

Background work (visit detection after a reboot, step sync, delivery of offline submissions) runs automatically on Android; no extra setup is needed.

Optional: AFCoreUI for Compose

The themed Compose component library is described in UI Components → Compose. It is consumed from source for now and is not yet published to GitHub Packages.

Learn more

See the API Reference. Complete integration guides are in AIDE Docs.