Skip to main content

API Reference

This page provides a comprehensive reference for the Nexad Android SDK's APIs.

Core SDK​

NexadSDK​

The main entry point for interacting with the SDK.

Initialization​

// Initialize the SDK
NexadSDK.initialize(
    context: Context,
    appId: String,
    publisherId: Long,
    publisherName: String,
    publisherType: PublisherType = PublisherType.CHATBOT
)

// Get the SDK instance (singleton)
val sdk = NexadSDK.getInstance()

Loading Ads​

// Load ads with minimal parameters
sdk.loadAd(
    placement: String,
    callback: AdLoadCallback
)

// Load ads with full parameters
sdk.loadAd(
    placement: String,
    context: ConversationContext? = null,
    adType: AdType? = null,
    renderMode: RenderMode = RenderMode.AUTO,
    styleId: String? = null,
    callback: AdLoadCallback
)

// Load native ads
sdk.loadNativeAd(
    placement: String,
    callback: AdDataLoadCallback
)

// Load WebView ads
sdk.loadWebViewAd(
    placement: String,
    callback: AdDataLoadCallback
)

// Load chat message embed ads
sdk.LoadChatMessageEmbedAd(
    chatbotContext: ChatbotContext,
    callback: GenericUILoadCallback<View>,
    style: AdViewStyle? = null,
    sessionId: String? = null
)

// Show modal overlay ads
sdk.showNativeModalAd(
    context: Context,
    callback: (Boolean, Exception?) -> Unit = { _, _ -> },
    style: AdViewStyle? = null,
    allowOpenRTB: Boolean = true,
    forceOpenRTB: Boolean = false,
    sessionId: String? = null
)

Ad View Management​

// Create a native ad view
sdk.createNativeAdView(
    context: Context,
    placement: String,
    style: AdViewStyle? = null
): NexadAdView

// Register an ad view for lifecycle management
sdk.registerView(
    view: View,
    ad: Ad
)

// Unregister an ad view
sdk.unregisterView(
    view: View
)

User Management​

// Set user information
sdk.setUser(
    user: NexadUser
)

// Get current user
sdk.getUser(): NexadUser?

// Clear user data
sdk.clearUserData()

Style Management​

// Set default ad view style
sdk.setDefaultAdViewStyle(
    style: AdViewStyle
)

// Get default ad view style
sdk.getDefaultAdViewStyle(): AdViewStyle

Ad Preloading​

// Preload ads
sdk.preloadAd(
    placement: String,
    context: ConversationContext? = null,
    count: Int = 1
)

// Get a preloaded ad
sdk.getPreloadedAd(
    placement: String,
    callback: AdLoadCallback
)

// Clear preloaded ads
sdk.clearPreloadedAds(
    placement: String? = null
)

Tracking and Analytics​

// Track URL
sdk.trackUrl(
    url: String
)

// Log event
sdk.logEvent(
    eventName: String,
    parameters: Map<String, Any>? = null
)

Cache Management​

// Clear cache
sdk.clearCache()

// Set cache size
sdk.setCacheSize(
    sizeInMB: Int
)

Data Models​

data class Ad(
    val id: String,
    val campaignId: Long,
    val adId: Long,
    val creativeId: Long,
    val title: String,
    val description: String? = null,
    val ctaText: String,
    val type: AdType,
    val imageUrl: String? = null,
    val iconUrl: String? = null,
    val imageWidth: Int? = null,
    val imageHeight: Int? = null,
    val iconWidth: Int? = null,
    val iconHeight: Int? = null,
    val styleTemplate: String? = null,
    val htmlContent: String? = null,
    val adMarkup: AdMarkup? = null,
    val renderMode: RenderMode = RenderMode.AUTO,
    val clickThroughUrl: String? = null,
    val trackingUrls: TrackingUrls? = null,
    val extraAttributes: Map<String, Any>? = null,
    val experimentVariant: String? = null
)

AdMarkup​

data class AdMarkup(
    val adm: String,           // Ad markup content
    val admType: String,       // Ad markup type
    val width: Int,            // Width
    val height: Int            // Height
)

TrackingUrls​

data class TrackingUrls(
    val clickTrackingUrls: List<String>? = null,  // Click tracking URLs
    val impressionUrls: List<String>? = null      // Impression tracking URLs
)

AdType​

enum class AdType {
    NATIVE_TEXT,         // Native rendering - text only
    NATIVE_IMAGE,        // Native rendering - image only
    NATIVE_TEXT_IMAGE,   // Native rendering - text and image
    HTML,                // WebView rendering - HTML ad
    BANNER,              // Banner ad
    VIDEO,               // Video ad
    DYNAMIC_TEMPLATE     // Dynamic template ad (supports both native/HTML rendering)
}

RenderMode​

enum class RenderMode {
    NATIVE,              // Force native rendering
    HTML,                // Force HTML rendering
    AUTO                 // Automatically select rendering mode based on ad type
}

NexadUser​

data class NexadUser(
    val userId: String,
    val deviceId: String,
    val clientId: String? = null,
    val userProfile: UserProfile? = null,
    val publisherUserId: String? = null,
    val email: String? = null,
    val ip: String? = null,
    val language: String? = null
)

UserProfile​

data class UserProfile(
    val nickname: String? = null,
    val age: Int? = null,
    val gender: Gender? = null,
    val interests: List<String>? = null,
    val location: Location? = null,
    val customAttributes: Map<String, String>? = null
)

Gender​

enum class Gender {
    MALE, FEMALE, OTHER, UNKNOWN
}

Location​

data class Location(
    val latitude: Double? = null,
    val longitude: Double? = null,
    val country: String? = null,
    val region: String? = null,
    val city: String? = null
)

ConversationContext​

data class ConversationContext(
    val sessionId: String,
    val query: String,
    val messages: List<Message>,
    val scene: SceneType = SceneType.CHAT_CONVERSATION,
    val chatbotContext: ChatbotContext? = null,
    val linkifySetting: LinkifySetting? = null,
    val customContext: Map<String, Any>? = null
)

SceneType​

enum class SceneType {
    CHAT_CONVERSATION,
    SEARCH_FEED
}

Message​

data class Message(
    val id: String,
    val sender: MessageSender,
    val content: String,
    val type: MessageType,
    val timestamp: Long,
    val tags: List<String>? = null
)

MessageSender​

enum class MessageSender {
    USER, BOT
}

MessageType​

enum class MessageType {
    TEXT, IMAGE, LINK, PRODUCT, AD
}

ChatbotContext​

data class ChatbotContext(
    val botName: String,
    val botDescription: String,
    val sessionId: String,
    val topic: String? = null,
    val conversations: List<Conversation>
)

Conversation​

data class Conversation(
    val timestamp: Long,
    val role: String,
    val content: String
)

LinkifySetting​

data class LinkifySetting(
    val queryId: String,
    val k: Int,
    val linkifyOnly: Boolean
)

UI Components​

AdViewStyle​

data class AdViewStyle(
    val size: AdSize? = null,
    val textStyle: TextStyle? = null,
    val backgroundColor: Int? = null,
    val border: BorderStyle? = null,
    val shadow: ShadowStyle? = null,
    val cornerRadius: Float = 0f,
    val imageStyle: ImageStyle? = null
) {
    companion object {
        fun default(): AdViewStyle
    }
}

TextStyle​

data class TextStyle(
    val titleColor: Int? = null,
    val descriptionColor: Int? = null,
    val ctaTextColor: Int? = null,
    val titleTextSize: Float? = null,
    val descriptionTextSize: Float? = null,
    val ctaTextSize: Float? = null,
    val titleFontFamily: Typeface? = null,
    val descriptionFontFamily: Typeface? = null,
    val ctaFontFamily: Typeface? = null
)

BorderStyle​

data class BorderStyle(
    val width: Float = 0f,
    val color: Int? = null,
    val style: BorderType = BorderType.SOLID
)

BorderType​

enum class BorderType {
    SOLID,
    DASHED,
    DOTTED
}

ShadowStyle​

data class ShadowStyle(
    val radius: Float = 0f,
    val dx: Float = 0f,
    val dy: Float = 0f,
    val color: Int? = null
)

AdSize​

data class AdSize(
    val width: Int,
    val height: Int
) {
    companion object {
        val MATCH_PARENT = AdSize(-1, -1)
        val WRAP_CONTENT = AdSize(-2, -2)
        val MEDIUM_RECTANGLE_300_250 = AdSize(300, 250)
    }
}

ImageStyle​

data class ImageStyle(
    val scaleType: ImageScaleType = ImageScaleType.FIT_CENTER,
    val cornerRadius: Float = 0f,
    val borderWidth: Float = 0f,
    val borderColor: Int? = null
)

ImageScaleType​

enum class ImageScaleType {
    FIT_CENTER,
    CENTER_CROP,
    CENTER_INSIDE,
    FIT_XY
}

Callback Interfaces​

AdLoadCallback​

interface AdLoadCallback {
    fun onSuccess(ad: Ad)
    fun onFailure(error: Exception)
}

AdDataLoadCallback​

interface AdDataLoadCallback {
    fun onSuccess(ads: List<Ad>)
    fun onFailure(error: Exception)
}

GenericUILoadCallback​

interface GenericUILoadCallback<T> {
    fun onSuccess(views: List<T>)
    fun onFailure(error: Exception)
}

Error Types​

// Network-related errors
class NetworkError(message: String, cause: Throwable? = null) : Exception(message, cause)

// Configuration errors
class InvalidConfiguration(message: String) : Exception(message)

// Ad loading errors
class AdLoadError(message: String, cause: Throwable? = null) : Exception(message, cause)

// Rendering errors
class RenderingError(message: String, cause: Throwable? = null) : Exception(message, cause)

Constants​

// Native ad view factory placements
object NativeAdViewFactory {
    const val PLACEMENT_DEFAULT = "default"
    const val PLACEMENT_CHAT_MESSAGE = "chat_message"
    const val PLACEMENT_SEARCH_RESULT = "search_result"
    const val PLACEMENT_BANNER = "banner"
}

// Publisher types
enum class PublisherType {
    CHATBOT,
    SEARCH_ENGINE,
    CONTENT_SITE,
    NEWS_APP,
    SOCIAL_MEDIA,
    OTHER
}