DOCSEARCHbyAlgolia
Submit Docs

Primal Android App

repository·main·Indexed 42 days ago

https://github.com/primalhq/primal-android-app

A Nostr social client for Android featuring a built-in Bitcoin Lightning wallet, long-form reads, and custom feeds. Built with Kotlin Multiplatform (KMP), Jetpack Compose, and MVI architecture, the app supports both AOSP and Google Play variants.

Tokens
977
Snippets
3
Records
6
Agent score
3%

What's inside Primal

  1. Primal Architecture and Tech Stack

    main

    Primal is a multi-module Android application built using the following technologies:

    • Core Framework: Kotlin Multiplatform (KMP)
    • UI: Jetpack Compose
    • Architecture: MVI (Model-View-Intent) + Clean Architecture
    • Dependency Injection: Hilt
    • Local Persistence: Room (using SQLCipher for encryption)

    It functions as a Nostr social client with integrated Bitcoin Lightning wallet capabilities.

  2. Build debug versions of Primal

    main

    Debug builds can be built without extra configuration. You can either run the Gradle task directly or use Android Studio to run the desired debug variant.

    To build via CLI, use:

    ./gradlew :app:assembleAospDebug
# OR
./gradlew :app:assembleGoogleDebug

    Note: Debug builds do not use encryption for sensitive information and have significantly slower performance compared to release builds.

    #!/bin/bash
./gradlew :app:assembleAospDebug

  3. Prerequisites for building Primal

    main

    Before building or running the Primal Android app, ensure your development environment meets the following requirements:

    • Java: version 21
    • Android SDK: compileSdk 36
    • Android Studio: latest stable version with AGP 8.13+ and Kotlin 2.2.x
    • Target Device/Emulator: Android 8.0+ (API 26)

    The app uses two product flavors (aosp and google) and multiple build types (debug, altRelease, and playRelease), resulting in variants like aospDebug, aospAltRelease, and googlePlayRelease.

  4. Install Primal on a device or emulator

    main

    After building, you can install the app using Gradle tasks or Android Studio.

    Installing Debug Builds

    To install a debug build:

    ./gradlew :app:installAospDebug

    Installing Release Builds

    To install a release build (e.g., aospAltRelease or googlePlayRelease):

    ./gradlew installAospAltRelease
# OR
./gradlew installGooglePlayRelease

    Note: If you attempt to install a release build without providing certificate properties in config.properties, it will fallback to using the debug certificate.

    # Install debug
./gradlew :app:installAospDebug

# Install release
./gradlew installAospAltRelease

  5. Configure and build release versions of Primal

    main

    Release builds require a config.properties file in the project root directory.

    Mandatory Configuration

    Every release build must include a keystore alias for encryption:

    localStorage.keyAlias={KeystoreAliasForEncryption}

    Custom Certificate Signing

    To sign release builds with your own certificate using the googlePlayRelease or aospAltRelease variants, add the following properties to config.properties. Replace {signingConfigName} with either playStore or alternative:

    playStore.storeFile={PathToYourCertificate}
playStore.storePassword={CertificatePassword}
playStore.keyAlias={YourAlias}
playStore.keyPassword={AliasPassword}
    localStorage.keyAlias={KeystoreAliasForEncryption}

# For custom signing:
playStore.storeFile={PathToYourCertificate}
playStore.storePassword={CertificatePassword}
playStore.keyAlias={YourAlias}
playStore.keyPassword={AliasPassword}

  6. Handle Play Store billing errors

    main

    When implementing or interacting with the Play Store billing integration in the Primal Android app, you may encounter specific InAppPurchaseException subclasses. These exceptions indicate why a purchase flow failed:

    • ProductNotAvailable: The specific product or SKU requested is not available for purchase (e.g., it has been deactivated or is not available in the user's region).
    • BillingNotAvailable: The Google Play Billing service is unavailable on the device (e.g., Play Store services are outdated, disabled, or not present).