ai.trygravity:gravity-sdk library to request Gravity ads from your Android app and show them with Jetpack Compose or Android Views. This page describes version 1.2.1. For the terms on this page, see Core concepts.
Before you start
- Your app targets Android 7.0 (API 24) or later.
- You have a Gravity API key. Get it from your dashboard under Settings → Platform Settings.
Install
Add the dependency to thebuild.gradle.kts file of your module:
INTERNET permission, so you do not need to add it. The SDK uses OkHttp and Kotlin Coroutines. The Compose dependencies are compileOnly, so your app gets them only if it already uses Compose.
Quick start
- Make one
Gravityinstance with aContextand your API key. It requests test ads until you setproduction = trueat go-live. - Call
gravity.getAds(...)with the conversation messages, the session ID, and the placements. Run it in a coroutine at the same time as your model call. - Show the ad with
SpecAd(Compose) orGravityAdView(Views).
Constructor
getAds()
userIP. The SDK sends it as device.ip. The SDK cannot detect the end user’s IP address by itself, so pass it when your server knows it.
The SDK collects device data (User-Agent, OS, device model, screen size, time zone, locale, and device type) and sends it with the request. The Device and Geography reports in your dashboard work with no extra code.
getAds() never throws. On a failure, it returns AdResult.EMPTY (no ads, status 0). AdResult has ads, status, elapsedMs, and error.
Model usage
The published SDK doesn’t have a model
usage option. To report model usage, send it in a direct HTTP request to the ad API: see Report model usage.userId, including for signed-out users. The default "anonymous" is excluded from per-user analytics. extraUserFields only accepts string values, so it can’t carry the nested user.tags object.
Placements
Show ads with Jetpack Compose
SpecAd draws the placement design that Gravity manages, and shows a built-in card when no valid design is available. It records the impression and the click, shows the required ad label and images, and shows feedback buttons.
GravityAd (in ai.trygravity.sdk.views) is the built-in Compose card without server-rendered designs. It takes ad, gravity, sessionId, modifier, and showFeedback.
Show ads with Android Views
For layouts in XML, useGravityAdView. It shows the built-in card, records the impression, and opens clickUrl on a tap. It does not show feedback buttons.
Custom renderer
If you show ads with your own UI, record the impression and the click yourself:Hash PII
To help attribution, send a hashed email and phone. The SDK hashes them on the device, so the raw values do not leave the device.Ad feedback
UsesendFeedback() if you make your own feedback UI. It sends the request in the background and ignores errors.
Full example: request ads during the model stream
FAQ
Does the ad request block my model response?
Does the ad request block my model response?
No. Use
async to start getAds() at the same time as your model stream. getAds() never throws. On a failure, it returns an empty list.Does the SDK collect the advertising ID (GAID)?
Does the SDK collect the advertising ID (GAID)?
No. The SDK does not send the Google advertising ID. If the user gave consent, you can send it:
extraDeviceFields = mapOf("ifa" to gaid).Which Android versions does the SDK support?
Which Android versions does the SDK support?
Android 7.0 (API 24) and later.