elimu.ai Analytics 📊

Android application which collects, provides and uploads learning event data.

Software Architecture

Learning Events

The various types of learning events are handled by the Android receivers at app/src/main/java/ai/elimu/analytics/receiver.

A learning event is an event without any corresponding testing of the student's mastery of a concept. For example; A student presses a word in a storybook and listens to its pronunciation.

• StoryBookLearningEvent
• WordLearningEvent
• LetterSoundLearningEvent (letter-sound correspondence)

Assessment Events

The various types of assessment events are handled by the Android receivers at app/src/main/java/ai/elimu/analytics/receiver.

An assessment event is an event that involves testing of whether or not the student is able to master a concept. For example; A word is sounded out, and the student is asked select the corresponding written text amongst a list of alternatives (multiple choice).

• WordAssessmentEvent
• LetterSoundAssessmentEvent (letter-sound correspondence)

Development 👩🏽‍💻

Compile APK:

./gradlew clean build

Install APK:

adb install app/build/outputs/apk/debug/app-debug.apk

Utils Library 📦

A utils library (.aar) makes it easier for other Android apps to report learning/assessment events.

• LearningEventUtil
• AssessmentEventUtil

See https://jitpack.io/#ai.elimu/analytics/ for the latest version.

How to Test -SNAPSHOT Versions of the Utils Library

1. Publish the library to your local Maven repository:

   ./gradlew clean assemble utils:publishToMavenLocal

2. In the app that will be testing the -SNAPSHOT version of the library, add mavenLocal():

   allprojects {
       repositories {
           google()
           mavenCentral()
           maven {
               url "https://jitpack.io"
           }
   +       mavenLocal()
       }
   }

3. Then change to your -SNAPSHOT version of the library:

   [versions]
   elimuModel = "model-2.0.101"
   -elimuAnalytics = "3.1.33"
   +elimuAnalytics = "3.1.34-SNAPSHOT"

Utils Usage Sample

Note

To use the utils library in another Android app, add the dependency in app/build.gradle:

implementation 'ai.elimu:analytics:<version>@aar'

For an example of an app that is reporting learning events, see https://github.com/elimu-ai/vitabu:

• https://github.com/elimu-ai/vitabu/blob/main/app/build.gradle#L51
• https://github.com/elimu-ai/vitabu/blob/main/app/src/main/java/ai/elimu/vitabu/ui/storybook/ChapterFragment.java#L150

Database Migration 🔀

Important

When adding a new database @Entity (or modifying an existing one), you need to prepare a database migration (SQL script) in app/src/main/java/ai/elimu/analytics/db/RoomDb.java.

Follow these steps:

1. Add the new/modified @Entity to app/src/main/java/ai/elimu/analytics/entity/
2. Include the entity in the entities section of the @Database in app/src/main/java/ai/elimu/analytics/db/RoomDb.java
3. Bump the @Database version in app/src/main/java/ai/elimu/analytics/db/RoomDb.java
4. Build the code with ./gradlew clean build
5. Open the new database schema generated at app/schemas/ai.elimu.analytics.db.RoomDb/<version>.json
   • Under entities, find the matching tableName and copy its SQL script from the createSql property.
6. Open RoomDb.java and add a new method for the latest migration
   • Paste the SQL script from the above JSON schema, and replace ${TABLE_NAME} with the name of the table you created/modified.
   • Include the migration in the getDatabase method in RoomDb.java.
7. To run the database migration, launch the application on your device.
8. To verify that your database migration ran successfully, look at the Logcat output and ensure that there are no RoomDb errors:

   2023-10-25 15:40:55.640 15303-914   RoomDb                  ai.elimu.analytics.debug             I  migrate (5 --> 6)
   2023-10-25 15:40:55.641 15303-914   RoomDb                  ai.elimu.analytics.debug             I  sql: CREATE TABLE IF NOT EXISTS 
   `LetterSoundCorrespondenceLearningEvent` (`letterSoundCorrespondenceLearningEventId` INTEGER, `androidId` TEXT NOT NULL, `packageName` TEXT NOT NULL, `time` 
   INTEGER NOT NULL, `id` INTEGER PRIMARY KEY AUTOINCREMENT)
   

Tip

You can also use Android Studio's Database Inspector to verify that the database migration succeeded:

Gradle Upgrade

./gradlew wrapper --gradle-version x.x.x

Release 📦

To perform a release, follow these steps:

1. Merge your PR into the main branch
2. Wait for the "Gradle Release" workflow to complete
3. Ensure that the new release version appears at https://github.com/elimu-ai/analytics/releases

Important

After you publish a new release, remember to also bump the version in all Android app repos that depend on the utils library:

• https://github.com/elimu-ai/appstore/blob/main/gradle/libs.versions.toml

---

elimu.ai - Free open-source learning software for out-of-school children ✨🚀

Website 🌐  •  Wiki 📃  •  Projects 👩🏽‍💻  •  Milestones 🎯  •  Community 👋🏽  •  Support 💜