API Reference

VelocityAds

`setUserId()`

fun setUserId(userId: String?)

Parameter	Type	Required	Description
`userId`	`String?`	No	User identifier

Call before initSDK() for best performance.

`initSDK()`

fun initSDK(
    context: Context,
    initRequest: VelocityAdsInitRequest,
    listener: VelocityAdsInitListener
)

Parameter	Type	Required	Description
`context`	`Context`	Yes	Application context
`initRequest`	`VelocityAdsInitRequest`	Yes	Built via `VelocityAdsInitRequest.Builder`
`listener`	`VelocityAdsInitListener`	Yes	Receives init success or failure

Utility Methods

Method	Description
`isInitialized(): Boolean`	Returns `true` if the SDK completed initialization successfully
`getSdkVersion(): String`	Returns the SDK version string
`setPluginInfo(type, version)`	Sets plugin metadata for cross-platform wrapper tracking. Call before `initSDK()`
`setDoNotSell(flag: Boolean)`	Sets the CCPA “Do Not Sell” preference
`setConsent(flag: Boolean)`	Sets the GDPR consent preference

VelocityNativeAd

The core ad object. Create one instance per ad placement, then call loadAd().

val nativeAd = VelocityNativeAd(adRequest)

`loadAd()` — Raw data

fun loadAd(listener: VelocityNativeAdListener)

Loads an ad and delivers raw creative data. Call registerViewForInteraction() inside onAdLoaded.

`loadAd()` — Compose card

fun loadAd(listener: VelocityNativeAdComposeListener)

The adRequest must be a VelocityNativeAdViewRequest. Delivers a @Composable lambda on success.

`loadAd()` — View card

fun loadAd(context: Context, listener: VelocityNativeAdViewListener)

The adRequest must be a VelocityNativeAdViewRequest. Delivers a ready-to-display android.view.View on success.

`registerViewForInteraction()`

fun registerViewForInteraction(
    adView: View,
    clickableViews: List<View>
)

Parameter	Type	Required	Description
`adView`	`View`	Yes	Root view — used for impression visibility detection
`clickableViews`	`List<View>`	Yes	Views that trigger `onAdClicked` when tapped

`unregisterViewForInteraction()`

fun unregisterViewForInteraction()

Removes all click and impression listeners previously registered.

`destroyAd()`

fun destroyAd()

Releases all SDK-internal state. Call in onDestroy() for every loaded ad.

Models

`VelocityNativeAdRequest`

VelocityNativeAdRequest.Builder()
    .withPrompt("user query")                // Optional
    .withAIResponse("ai response")           // Optional
    .withConversationHistory(history)        // Optional
    .withAdditionalContext("travel, summer") // Optional
    .withAdUnitId("my-unit-id")              // Optional
    .build()

`VelocityNativeAdViewRequest`

Extends VelocityNativeAdRequest with size and theming for rendered ad formats.

VelocityNativeAdViewRequest.Builder(VelocityAdViewSize.M)
    .withPrompt("user query")
    .withAdConfiguration(AdConfiguration())  // Optional
    .build()

`NativeAd` (ad creative data)

Accessed via VelocityNativeAd.data after a successful load.

Field	Type	Description
`adId`	`String`	Unique ad load identifier
`title`	`String`	Ad headline
`description`	`String`	Ad body text
`callToAction`	`String`	CTA button text
`advertiserName`	`String`	Advertiser/brand name
`sponsoredLabel`	`String`	Sponsorship label
`badgeLabel`	`String`	Badge text (e.g. “ad”)
`advertiserIconUrl`	`String`	Advertiser logo/icon URL
`largeImageUrl`	`String?`	Main ad image URL (optional)
`squareImageUrl`	`String?`	Square ad image URL (optional)
`clickUrl`	`String`	URL opened on ad click
`impressionUrl`	`String`	Impression tracking URL

`VelocityAdViewSize`

enum class VelocityAdViewSize(val heightDp: Int) {
    S(50),   // Small
    M(100),  // Medium
    L(300)   // Large
}

`AdConfiguration`

data class AdConfiguration(
    val colorScheme: AdColorScheme? = null,
    val adTypography: AdTypography? = null,
    val darkTheme: Boolean? = null   // null = follow system
)

Listeners

`VelocityAdsInitListener`

interface VelocityAdsInitListener {
    fun onInitSuccess()
    fun onInitFailure(error: VelocityAdsError)
}

Both methods are always invoked on the main thread.

`VelocityAdsInitRequest.Builder`

VelocityAdsInitRequest.Builder(appKey: String)
    .withDebug(debug: Boolean)  // optional, defaults to false
    .build()

`VelocityNativeAdListener`

interface VelocityNativeAdListener {
    fun onAdLoaded(nativeAd: VelocityNativeAd)
    fun onAdFailedToLoad(nativeAd: VelocityNativeAd, error: VelocityAdsError)
    fun onAdImpression(nativeAd: VelocityNativeAd)
    fun onAdClicked(nativeAd: VelocityNativeAd)
}

Method	Description
`onAdLoaded`	Main thread. Ad loaded — `nativeAd.data` is populated. Call `registerViewForInteraction` here
`onAdFailedToLoad`	Ad request failed. `nativeAd.data` is not accessible
`onAdImpression`	Fired once when the registered `adView` is ≥ 50% visible on screen
`onAdClicked`	Fired each time the user taps a registered clickable view

`VelocityNativeAdComposeListener`

interface VelocityNativeAdComposeListener {
    fun onAdLoaded(nativeAd: VelocityNativeAd, adContent: @Composable () -> Unit)
    fun onAdFailedToLoad(nativeAd: VelocityNativeAd, error: VelocityAdsError)
    fun onAdImpression(nativeAd: VelocityNativeAd)
    fun onAdClicked(nativeAd: VelocityNativeAd)
}

`VelocityNativeAdViewListener`

interface VelocityNativeAdViewListener {
    fun onAdLoaded(nativeAd: VelocityNativeAd, nativeAdView: View)
    fun onAdFailedToLoad(nativeAd: VelocityNativeAd, error: VelocityAdsError)
    fun onAdImpression(nativeAd: VelocityNativeAd)
    fun onAdClicked(nativeAd: VelocityNativeAd)
}

Error Codes

`VelocityAdsError`

data class VelocityAdsError(val code: Int, val message: String)

`VelocityAdsErrorCode`

Code	Constant	Meaning
1000	`INVALID_URL`	Malformed URL
1001	`NETWORK_ERROR`	Network request failed
1002	`JSON_PARSE_ERROR`	Response JSON could not be parsed
1003	`INVALID_RESPONSE`	Response structure is invalid
1004	`EMPTY_RESPONSE_BODY`	Server returned an empty body
1005	`SERVER_ERROR_FIELD`	Server returned an error field
1006	`HTTP_FAILURE`	HTTP status code indicates failure
2000	`INVALID_APP_KEY`	`appKey` is empty or blank
2001	`SDK_NOT_INITIALIZED`	`loadAd` called before `initSDK`
2002	`SDK_INITIALIZATION_IN_PROGRESS`	`initSDK` called while already initializing
2003	`LOAD_ALREADY_IN_PROGRESS`	`loadAd` called while already loading
2004	`LOAD_SERVICE_UNAVAILABLE`	Internal bidder service not available
2005	`INVALID_AD_RESPONSE`	Ad response is missing required data
2006	`NO_FILL`	No ad available for the given context
2007	`INTERNAL_ERROR`	Unexpected internal SDK error
2008	`INVALID_AD_REQUEST`	Wrong request type passed to a load method
2009	`WATERFALL_LOAD_FAILED`	Waterfall load failed

Android SDK

More

VelocityAds

`setUserId()`

`initSDK()`

Utility Methods

VelocityNativeAd

`loadAd()` — Raw data

`loadAd()` — Compose card

`loadAd()` — View card

`registerViewForInteraction()`

`unregisterViewForInteraction()`

`destroyAd()`

Models

`VelocityNativeAdRequest`

`VelocityNativeAdViewRequest`

`NativeAd` (ad creative data)

`VelocityAdViewSize`

`AdConfiguration`

Listeners

`VelocityAdsInitListener`

`VelocityAdsInitRequest.Builder`

`VelocityNativeAdListener`

`VelocityNativeAdComposeListener`

`VelocityNativeAdViewListener`

Error Codes

`VelocityAdsError`

`VelocityAdsErrorCode`

Android SDK

More

​VelocityAds

​setUserId()

​initSDK()

​Utility Methods

​VelocityNativeAd

​loadAd() — Raw data

​loadAd() — Compose card

​loadAd() — View card

​registerViewForInteraction()

​unregisterViewForInteraction()

​destroyAd()

​Models

​VelocityNativeAdRequest

​VelocityNativeAdViewRequest

​NativeAd (ad creative data)

​VelocityAdViewSize

​AdConfiguration

​Listeners

​VelocityAdsInitListener

​VelocityAdsInitRequest.Builder

​VelocityNativeAdListener

​VelocityNativeAdComposeListener

​VelocityNativeAdViewListener

​Error Codes

​VelocityAdsError

​VelocityAdsErrorCode

VelocityAds

`setUserId()`

`initSDK()`

Utility Methods

VelocityNativeAd

`loadAd()` — Raw data

`loadAd()` — Compose card

`loadAd()` — View card

`registerViewForInteraction()`

`unregisterViewForInteraction()`

`destroyAd()`

Models

`VelocityNativeAdRequest`

`VelocityNativeAdViewRequest`

`NativeAd` (ad creative data)

`VelocityAdViewSize`

`AdConfiguration`

Listeners

`VelocityAdsInitListener`

`VelocityAdsInitRequest.Builder`

`VelocityNativeAdListener`

`VelocityNativeAdComposeListener`

`VelocityNativeAdViewListener`

Error Codes

`VelocityAdsError`

`VelocityAdsErrorCode`