Quickstart with Android (Kotlin)

This quickstart walks you through minting an API token, adding the PromptHelm Android SDK to a Gradle project, and making your first call from Kotlin. By the end you will have a working completion, a Kotlin Flow streaming example, and a checklist for shipping to the Play Store.

1. 1

   Generate an API token

   Sign in to the dashboard and open Settings → API tokens. Click New token, name it (e.g. android-app-dev), and copy the value immediately — tokens are revealed exactly once.

   Keep the token out of source control

   Never commit an API token to your repository. Read it from gradle.properties (gitignored), inject it into BuildConfig for local builds, and use a secrets manager or remote config for release builds.

2. 2

   Add the SDK

   Add the dependency to your app module's build.gradle.kts. The artifact is published to Maven Central, so no extra repository configuration is required if you already declare mavenCentral() in your settings.gradle.kts.

   dependencies {
       implementation("app.prompthelm:sdk-android:0.1.0")
   }

   Make sure your manifest declares the network permission:

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

3. 3

   Wire up BuildConfig

   Read the API key from local.properties (gitignored) and surface it on BuildConfig so it never lives in source.

   import java.util.Properties
   
   val localProps = Properties().apply {
       val f = rootProject.file("local.properties")
       if (f.exists()) f.inputStream().use { load(it) }
   }
   
   android {
       defaultConfig {
           buildConfigField(
               "String",
               "PROMPTHELM_API_KEY",
               "\"${localProps.getProperty("promptHelmApiKey", "")}\"",
           )
       }
       buildFeatures { buildConfig = true }
   }

4. 4

   Create your first prompt

   In the dashboard, navigate to Prompts → New prompt. Give it a slug (for example, welcome), pick a default model, and write the prompt body. Use {{ variable_name }} for runtime variables. Saving publishes v1 on the main environment.

   Learn more

   See Concepts → Prompts for versions, environments, and promotion semantics.

5. 5

   Call it from Kotlin

   Construct a single PromptHelm instance per process — typically inside your Application subclass or a Hilt @Singleton provider — and call execute from a coroutine.

   import app.prompthelm.sdk.PromptHelm
   
   val ph = PromptHelm(apiKey = BuildConfig.PROMPTHELM_API_KEY)
   
   val response = ph.execute(ExecuteRequest(
       promptSlug = "welcome",
       variables = mapOf("name" to "World")
   ))
   
   println(response.output)

   The call appears in the dashboard's Logs view with the full request/response payload, the per-call cost, and the round-trip latency.

6. 6

   Stream with Flow

   For chat-style UIs, switch to the streaming API. The SDK exposes a cold Flow<StreamEvent> that surfaces typed chunks as they arrive.

   ph.stream(ExecuteRequest(promptSlug = "welcome", variables = mapOf("name" to "World")))
       .collect { event ->
           when (event) {
               is StreamEvent.Chunk -> print(event.content)
               is StreamEvent.Done  -> println("\n${event.totalTokens} tokens, $${event.cost}")
               is StreamEvent.Err   -> println("Error ${event.errorCode}: ${event.message}")
           }
       }

   Cancelling the enclosing CoroutineScope (for example a viewModelScope when the user leaves the screen) cancels the SSE connection automatically.

7. 7

   Ship to production

   Before you publish to the Play Store, run through this checklist:

   • Source the API key from a secrets manager in release builds (or Firebase Remote Config). BuildConfig injection is fine for debug builds; never ship a production key embedded in the APK.
   • R8 / ProGuard rules ship inside the SDK as consumer-rules.pro, so you do not need to add keep rules in your app module. Verify with a release build that streaming events still deserialise correctly.
   • Cancel coroutines on lifecycle teardown. Use viewModelScope or lifecycleScope so cancellation propagates to the SDK and closes open SSE streams.
   • Catch typed errors. Every SDK call throws PromptHelmException with a stable errorCode. Map known codes to retries; let unknown codes surface to your crash reporter.
   • Pin an environment. Default main to Play Store traffic and promote new prompt versions through staging and dev first.

Next steps