API Reference

GrowlAdSDK

The main singleton object for SDK operations. Handles server communication, visitor identification, and message recording.

Properties

SESSION_ID

val SESSION_ID: String

A process-scoped unique identifier for the app session. Persists across activity transitions but regenerates if the app is killed.

Methods

getVisitorId

suspend fun getVisitorId(context: Context): String

Retrieves or generates a persistent visitor ID for ad targeting.

Behavior:

Attempts to get Google Advertising ID (GAID)
Falls back to locally stored UUID if GAID is unavailable or ad tracking is disabled
Fallback ID format: anon_{UUID}
Persisted in SharedPreferences for consistency

Parameters:

Parameter	Type	Description
`context`	`Context`	Android context

Returns: Visitor ID string

getUserId

fun getUserId(context: Context): String

Retrieves or generates a persistent user ID.

Behavior:

Checks SharedPreferences for existing user ID
If not found, generates a new UUID and persists it
Returns the same ID on subsequent calls

Parameters:

Parameter	Type	Description
`context`	`Context`	Android context

Returns: User ID string (UUID format)

recordMessage

suspend fun recordMessage(
    context: Context,
    role: MessageRole,
    message: String,
    chatId: String,
    userId: String,
    publisherId: String
): Boolean

Records a message to Growl’s analytics backend for ad targeting.

Parameters:

Parameter	Type	Description
`context`	`Context`	Android context
`role`	`MessageRole`	`USER` or `ASSISTANT`
`message`	`String`	Message text content
`chatId`	`String`	Conversation identifier
`userId`	`String`	User identifier
`publisherId`	`String`	Your Publisher ID

Returns: true if successful (HTTP 2xx), false otherwise

fetchAdForChat

suspend fun fetchAdForChat(
    context: Context,
    chatHistory: List<ChatMessage>,
    publisherId: String,
    adUnitId: String,
    chatId: String
)

Fetches an ad most appropriate for the given chat history ot null if no ad needs to be shown.

Parameters:

Parameter	Type	Description
`context`	`Context`	Android context
`chatHistory`	`List<ChatMessage>`	Chat messages
`chatId`	`String`	Conversation identifier
`adUnitId`	`String`	Ad Unit identifier
`publisherId`	`String`	Your Publisher ID

Returns: Ad object if successful (HTTP 2xx), null otherwise

GrowlAdView

A Material Design card view for displaying contextual ads.

Methods

displayAd

fun displayAd(ad: Ad?)

Displays a cached ad directly without fetching.

Parameter	Type	Description
`ad`	`Ad`	Cached ad

reset

fun reset()

Resets the view to its initial state.

applyStyling

fun applyStyling(params: StylingParams)

Applies custom styling to the ad view.

Parameters:

Parameter	Type	Description
`params`	`StylingParams`	Styling configuration

StylingParams

data class StylingParams(
    val background: Int? = null,
    val text: Int? = null,
    val border: Int? = null,
    val borderWidth: Int? = null
)

Property	Type	Description
`background`	`Int?`	Card background color
`text`	`Int?`	Text color for title and description
`border`	`Int?`	Card border/stroke color
`borderWidth`	`Int?`	Border width in dp

GrowlChatListAdapter

A RecyclerView ListAdapter for displaying chat messages and ads with DiffUtil support.

Constructors

GrowlChatListAdapter(
    adUnitId: String,
    publisherId: String,
    chatId: String,
    getChatHistory: () -> List<ChatMessage>,
    stylingParams: GrowlAdView.StylingParams? = null,
    adFetchingScope: CoroutineScope = CoroutineScope(Dispatchers.IO)
)

Parameters:

Parameter	Type	Description
`adUnitId`	`String`	Your Ad Unit ID
`publisherId`	`String`	Your Publisher ID
`chatId`	`String`	Conversation identifier
`getChatHistory`	`() -> List<ChatMessage>`	Function returning current chat history
`stylingParams`	`StylingParams?`	Optional ad styling
`adFetchingScope`	`CoroutineScope`	Scope for ad fetching coroutines

GrowlChatListAdapter(
    adUnitId: String,
    publisherId: String,
    chatId: String,
    createMessageViewHolder: (parent: ViewGroup) -> MessageViewHolder<out ChatItem.MessageItem>,
    getChatHistory: () -> List<ChatMessage>,
    stylingParams: GrowlAdView.StylingParams? = null,
    adFetchingScope: CoroutineScope = CoroutineScope(Dispatchers.IO)
)

Parameters:

Parameter	Type	Description
`adUnitId`	`String`	Your Ad Unit ID
`publisherId`	`String`	Your Publisher ID
`chatId`	`String`	Conversation identifier
`createMessageViewHolder`	`(ViewGroup) -> MessageViewHolder`	Factory for message view holders
`getChatHistory`	`() -> List<ChatMessage>`	Function returning current chat history
`stylingParams`	`StylingParams?`	Optional ad styling
`adFetchingScope`	`CoroutineScope`	Scope for ad fetching coroutines

Methods

submitList

fun submitList(list: List<ChatItem>?)

Updates the adapter with a new list. DiffUtil calculates changes automatically.

GrowlChatRecyclerAdapter

A basic RecyclerView Adapter for displaying chat messages and ads. Requires manual notification of changes.

Constructors

GrowlChatRecyclerAdapter(
    adUnitId: String,
    publisherId: String,
    chatId: String,
    items: List<ChatItem>,
    getChatHistory: () -> List<ChatMessage>,
    stylingParams: GrowlAdView.StylingParams? = null,
    adFetchingScope: CoroutineScope = CoroutineScope(Dispatchers.IO)
)

Parameters:

Parameter	Type	Description
`adUnitId`	`String`	Your Ad Unit ID
`publisherId`	`String`	Your Publisher ID
`chatId`	`String`	Conversation identifier
`items`	`List<ChatItem>`	List of items to be displayed
`getChatHistory`	`() -> List<ChatMessage>`	Function returning current chat history
`stylingParams`	`StylingParams?`	Optional ad styling
`adFetchingScope`	`CoroutineScope`	Scope for ad fetching coroutines

GrowlChatRecyclerAdapter(
    adUnitId: String,
    publisherId: String,
    chatId: String,
    items: List<ChatItem>,
    createMessageViewHolder: (parent: ViewGroup) -> MessageViewHolder<out ChatItem.MessageItem>,
    getChatHistory: () -> List<ChatMessage>,
    stylingParams: GrowlAdView.StylingParams? = null,
    adFetchingScope: CoroutineScope = CoroutineScope(Dispatchers.IO)
)

Parameters:

Parameter	Type	Description
`adUnitId`	`String`	Your Ad Unit ID
`publisherId`	`String`	Your Publisher ID
`chatId`	`String`	Conversation identifier
`items`	`List<ChatItem>`	List of items to be displayed
`createMessageViewHolder`	`(ViewGroup) -> MessageViewHolder`	Factory for message view holders
`getChatHistory`	`() -> List<ChatMessage>`	Function returning current chat history
`stylingParams`	`StylingParams?`	Optional ad styling
`adFetchingScope`	`CoroutineScope`	Scope for ad fetching coroutines

MessageViewHolder

Abstract base class for custom message view holders.

abstract class MessageViewHolder<T : ChatItem.MessageItem>(
    itemView: View
) : RecyclerView.ViewHolder(itemView) {

    abstract fun bind(messageItem: T, position: Int)
}

Extend this class to create your own message view holder:

class MyMessageViewHolder(
    private val binding: ItemMessageBinding
) : MessageViewHolder<MyMessage>(binding.root) {

    override fun bind(messageItem: MyMessage, position: Int) {
        binding.textView.text = messageItem.text
    }
}

Data Models

ChatItem

Sealed class representing items in the chat list.

sealed class ChatItem {
    abstract val chatItemId: String

    abstract class MessageItem(
        override val chatItemId: String
    ) : ChatItem()

    data class AdItem(
        override val chatItemId: String = UUID.randomUUID().toString(),
        var hasAttemptedLoad: Boolean = false,
        var loadedAd: Ad? = null
    ) : ChatItem()
}

ChatMessage

Message data sent to the API for ad context.

data class ChatMessage(
    val role: String,   // "user" or "assistant"
    val content: String // Message text
)

Ad data returned from the API.

data class Ad(
    val title: String,
    val link: String,
    val description: String? = null,
    val image: String? = null,
    val id: String? = null
)

MessageRole

Enum for message sender types.

enum class MessageRole(val roleName: String) {
    USER("user"),
    ASSISTANT("assistant")
}

Interfaces

AdLoadCallback

Callback interface for ad load events.

interface AdLoadCallback {
    fun onAdsLoaded(ads: List<Ad>)
    fun onError(error: String)
}

Constants

API Endpoints

Build Type	Base URL
Debug	`https://dev-api.withgrowl.com/v1`
Release	`https://api.withgrowl.com/v1`

Error Handling

The SDK handles errors gracefully:

Network errors: Logged with Log.e(), view hides automatically
Empty responses: Ad view is hidden
Image load failures: Placeholder color is shown
GAID unavailable: Falls back to persistent UUID
Recording failures: Returns false, doesn’t throw exceptions

Package Structure

com.withgrowl.growlandroidsdk
├── GrowlAdSDK              // Main SDK singleton
├── GrowlAdView             // Ad display view
├── GrowlConstants          // API URLs
├── MessageRole             // USER/ASSISTANT enum
├── AdLoadCallback          // Ad load callback interface
│
├── models/
│   ├── Ad                  // Ad data
│   ├── ChatItem            // Sealed class (MessageItem, AdItem)
│   ├── ChatMessage         // Message for API
│   ├── GenerateRequest     // Internal API request
│   └── GenerateResponse    // Internal API response
│
├── recycler/
│   ├── GrowlChatListAdapter      // DiffUtil adapter (recommended)
│   ├── GrowlChatRecyclerAdapter  // Basic adapter
│   ├── MessageViewHolder         // Abstract message holder
│   └── AdViewHolder              // Internal ad holder
│
├── prefs/
│   ├── PreferenceStore           // Storage interface
│   └── SharedPreferenceStore     // SharedPreferences impl
│
└── glide/
    ├── GrowlGlideModule          // Glide configuration
    ├── SvgDecoder                // SVG support
    ├── SvgDrawableTranscoder     // SVG conversion
    └── SvgSoftwareLayerSetter    // SVG rendering