Android SDK - Gravity

Installation

Add the dependency to your module’s build.gradle.kts:

dependencies {
    implementation("ai.trygravity:gravity-sdk:1.0.0")
}

The SDK requires INTERNET permission (declared in its manifest — no action needed).

How the pieces fit together

Initialize the client

Create a Gravity instance with your API key, a Context, and production = true.

Collect context & fetch ads

Call gravity.getAds(...) with the conversation messages, session ID, and placements. The SDK auto-collects device signals (UA, OS, screen, timezone). Run it in parallel with your LLM call using coroutines.

Render

Use the built-in GravityAd Compose composable, GravityAdView (Views), or render the ad data yourself. Impression tracking fires automatically.

Quick start

import ai.trygravity.sdk.Gravity
import ai.trygravity.sdk.models.*

// 1. Initialize (once, e.g. in your ViewModel or Application)
val gravity = Gravity(context, apiKey = "pub_...", production = true)

// 2. Fetch ads in parallel with your LLM call
val messages = listOf(
    Message("user", "What's the best way to deploy a Postgres DB?"),
    Message("assistant", "Here are some options..."),
)

viewModelScope.launch {
    val adDeferred = async { gravity.getAds(
        messages = messages,
        sessionId = "sess_abc123",
        userId = currentUser.id,
        placements = listOf(Placement.belowResponse()),
    ) }

    // Stream your LLM response...
    val result = adDeferred.await()

    // 3. Render
    result.ads.firstOrNull()?.let { ad ->
        // Use GravityAd composable or your own UI
    }
}

Constructor

Gravity(
    context: Context,
    apiKey: String = System.getenv("GRAVITY_API_KEY") ?: "",
    apiUrl: String = "https://server.trygravity.ai/api/v1/ad",
    timeoutSeconds: Long = 3L,
    production: Boolean = false,
    relevancy: Double = 0.2,
    excludedTopics: List<String>? = null,
)

Parameter	Type	Default	Description
`context`	`Context`	—	Android context for device signal collection
`apiKey`	`String`	`GRAVITY_API_KEY` env var	Your Gravity publisher API key
`timeoutSeconds`	`Long`	`3`	Abort after this many seconds
`production`	`Boolean`	`false`	`false` returns test ads (no billing)
`relevancy`	`Double`	`0.2`	Minimum relevancy threshold 0.0–1.0
`excludedTopics`	`List<String>?`	`null`	Topics to exclude from matching

`getAds()`

suspend fun getAds(
    messages: List<Message>,
    sessionId: String,
    userId: String = "anonymous",
    placements: List<Placement>,
    userIP: String? = null,
    hashedIdentity: HashedIdentity? = null,
    extraUserFields: Map<String, String>? = null,
    extraDeviceFields: Map<String, Any>? = null,
    production: Boolean? = null,
    relevancy: Double? = null,
): AdResult

The SDK auto-collects device signals (User-Agent, OS, model, screen size, timezone, locale, device type) and sends them with the request. Your dashboard’s Device and Geography breakdowns work automatically.

getAds() never throws. On any failure, it returns AdResult.EMPTY (empty ads list). Safe to fire-and-forget.

Placements

Placement.belowResponse()           // "below_response"
Placement.inlineResponse()          // "inline_response"
Placement.aboveResponse()           // "above_response"

// Custom
Placement("right_response", "sidebar")

Jetpack Compose — render ads

import ai.trygravity.sdk.views.SpecAd

@Composable
fun ChatScreen(response: String, ads: List<AdResponse>, gravity: Gravity, sessionId: String) {
    Column {
        Text(response)
        ads.firstOrNull()?.let { ad ->
            SpecAd(
                ad = ad,
                gravity = gravity,
                sessionId = sessionId,
            )
        }
    }
}

SpecAd automatically handles the Gravity-managed placement design, safe fallback, impression and click tracking, required ad disclosure, images, and server-requested feedback controls.

Parameter	Type	Description
`ad`	`AdResponse`	The ad object from `getAds()`
`gravity`	`Gravity`	Client instance for tracking
`sessionId`	`String`	Must match the ad request
`showFeedback`	`Boolean`	Allow feedback controls. Default `true`. The prompt renders only when this is `true` and the server marked the ad with `feedbackPrompt: true` (selective — borderline-relevance / tight-auction ads). One tap submits and swaps to “Thanks for the feedback”; feedback taps never trigger the ad click.

Android Views

For XML-based layouts, use GravityAdView:

import ai.trygravity.sdk.views.GravityAdView

val adView = GravityAdView(
    context = this,
    ad = ad,
    gravity = gravity,
    sessionId = sessionId,
)
container.addView(adView)

Custom rendering

If you render ads with your own UI, fire tracking manually:

// Impression — fire once when the ad becomes visible
gravity.trackImpression(ad)

// Click — always use clickUrl, not url
ad.clickUrl?.let { url ->
    startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
}

PII hashing

Hash email and phone for attribution without sending raw values:

import ai.trygravity.sdk.hashPII

val hashed = hashPII(email = user.email, phone = user.phone)

val result = gravity.getAds(
    messages = messages,
    sessionId = sessionId,
    userId = user.id,
    placements = listOf(Placement.belowResponse()),
    hashedIdentity = hashed,
)

Ad feedback

// Thumbs up
gravity.sendFeedback(
    sessionId = sessionId,
    ad = ad,
    sentiment = Gravity.Sentiment.THUMBS_UP,
)

// Thumbs down with reasons
gravity.sendFeedback(
    sessionId = sessionId,
    ad = ad,
    sentiment = Gravity.Sentiment.THUMBS_DOWN,
    reasons = listOf("not_interested", "irrelevant"),
)

Full example — parallel with LLM stream

import ai.trygravity.sdk.Gravity
import ai.trygravity.sdk.models.*

class ChatViewModel(application: Application) : AndroidViewModel(application) {
    private val gravity = Gravity(application, apiKey = "pub_...", production = true)

    val ads = MutableStateFlow<List<AdResponse>>(emptyList())
    val response = MutableStateFlow("")

    fun send(messages: List<Message>, sessionId: String, userId: String) {
        viewModelScope.launch {
            // Fire ad request in parallel
            val adDeferred = async {
                gravity.getAds(
                    messages = messages,
                    sessionId = sessionId,
                    userId = userId,
                    placements = listOf(Placement.belowResponse()),
                )
            }

            // Stream LLM response
            streamLLM(messages).collect { chunk ->
                response.update { it + chunk }
            }

            // Append ads
            ads.value = adDeferred.await().ads
        }
    }
}

FAQ

Does the ad request block my LLM response?

No. Use async to fire getAds() in parallel with your LLM stream. It never throws — failures return an empty list.

Does the SDK collect the Advertising ID (GAID)?

No. The SDK does not access Google Advertising ID. If you have user consent, pass it as extraDeviceFields = mapOf("ifa" to gaid).

What Android versions are supported?

Android 7.0+ (API 24+).

What dependencies does the SDK add?

OkHttp for networking and Kotlin Coroutines. Compose dependencies are compileOnly — only pulled in if your app already uses Compose.

​Installation

​How the pieces fit together

​Quick start

​Constructor

​getAds()

​Placements

​Jetpack Compose — render ads

​Android Views

​Custom rendering

​PII hashing

​Ad feedback

​Full example — parallel with LLM stream

​FAQ

Installation

How the pieces fit together

Quick start

Constructor

`getAds()`

Placements

Jetpack Compose — render ads

Android Views

Custom rendering

PII hashing

Ad feedback

Full example — parallel with LLM stream

FAQ