Skip to content
Growl Docs

Android SDK

The Growl Android SDK enables you to display contextual ads in your Android chat applications. The SDK analyzes conversation context to deliver relevant advertisements that enhance user experience while generating revenue.

Requirements

Section titled “Requirements”
  • Minimum SDK: API 26 (Android 8.0)
  • Compile SDK: API 34+
  • Kotlin: 1.8+
  • Java Compatibility: Java 11

Installation

Section titled “Installation”

Add the Growl Android SDK to your app’s build.gradle.kts:

dependencies {
    implementation("com.withgrowl:growl-android-sdk:1.2.6")
}

Configuration

Section titled “Configuration”

Storing Credentials

Section titled “Storing Credentials”

Store your credentials securely to avoid leaking them via version control. Add them to your local.properties file:

PUBLISHER_ID=YOUR_PUBLISHER_ID
AD_UNIT_ID=YOUR_AD_UNIT_ID

Accessing Credentials via BuildConfig

Section titled “Accessing Credentials via BuildConfig”

Enable BuildConfig in your module-level build.gradle.kts:

android {
    buildFeatures {
        buildConfig = true
    }


    // for older gradle versions
    defaultConfig {
        // Read from local.properties
        val localProperties = Properties()
        localProperties.load(rootProject.file("local.properties").inputStream())


        buildConfigField("String", "PUBLISHER_ID", "\"${localProperties["PUBLISHER_ID"]}\"")
        buildConfigField("String", "AD_UNIT_ID", "\"${localProperties["AD_UNIT_ID"]}\"")
    }
}

Then access them in your code:

private val PUBLISHER_ID = BuildConfig.PUBLISHER_ID
private val AD_UNIT_ID = BuildConfig.AD_UNIT_ID

Permissions

Section titled “Permissions”

The SDK requires the following permissions (automatically merged from the SDK manifest):

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Quick Start

Section titled “Quick Start”

The SDK provides two main integration points:

  1. GrowlChatListAdapter - For displaying ads inline with chat messages (recommended)
  2. GrowlAdSDK.recordMessage() - For sending chat data to Growl for better ad targeting

  1. Create your message data class

    Your message class must extend ChatItem.MessageItem:

    import com.withgrowl.growlandroidsdk.MessageRole
    import com.withgrowl.growlandroidsdk.models.ChatItem
    

    data class MyMessage(
        override val chatItemId: String,
        val sender: MessageRole,
        val text: String
    ) : ChatItem.MessageItem(chatItemId)

  2. Create your MessageViewHolder

    Extend the SDK’s MessageViewHolder to define how your messages are displayed:

    import com.withgrowl.growlandroidsdk.recycler.MessageViewHolder
    

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

        override fun bind(messageItem: MyMessage, position: Int) {
            binding.textView.text = messageItem.text
            // Style based on sender (user vs assistant)
        }
    }

  3. Set up the adapter

    import com.withgrowl.growlandroidsdk.GrowlAdView
    import com.withgrowl.growlandroidsdk.recycler.GrowlChatListAdapter
    import androidx.core.graphics.toColorInt
    

    val adapter = GrowlChatListAdapter(
        adUnitId = AD_UNIT_ID,
        publisherId = PUBLISHER_ID,
        chatId = "unique-chat-id",
        createMessageViewHolder = { parent ->
            val binding = ItemMessageBinding.inflate(
                LayoutInflater.from(parent.context), parent, false
            )
            MyMessageViewHolder(binding)
        },
        getChatHistory = { getChatHistoryForAds() },
        stylingParams = GrowlAdView.StylingParams(
            background = "#1C1E22".toColorInt(),
            text = "#EEEEEE".toColorInt(),
            border = "#2F2F2F".toColorInt(),
            borderWidth = 1
        )
    )
    

    recyclerView.adapter = adapter

  4. Update the list when messages change

    private fun fetchAndInsertAdIfAvailable() {
        lifecycleScope.launch {
            val ad = GrowlAdSDK.fetchAdForChat(
                context = requireContext(),
                chatHistory = chatHistory,
                publisherId = PUBLISHER_ID,
                adUnitId = AD_UNIT_ID,
                chatId = dashboardViewModel.chatId
            )
    

            if (ad != null) {
                // Add an ad slot
                chatItems.add(ChatItem.AdItem(
                    hasAttemptedLoad = true,
                    loadedAd = ad
                ))
    

                // Submit the updated list
                adapter.submitList(chatItems.toList())
            }
        }
    }
    // Add a user message
    chatItems.add(MyMessage(
        chatItemId = UUID.randomUUID().toString(),
        sender = MessageRole.USER,
        text = userInput
    ))
    

    // Add an AI response
    chatItems.add(MyMessage(
        chatItemId = UUID.randomUUID().toString(),
        sender = MessageRole.ASSISTANT,
        text = aiResponse
    ))
    

    // Add an ad slot after AI response
    fetchAndInsertAdIfAvailable()

  5. Record messages for better targeting

    import com.withgrowl.growlandroidsdk.GrowlAdSDK
    

    lifecycleScope.launch {
        GrowlAdSDK.recordMessage(
            context = requireContext(),
            role = MessageRole.USER,
            message = userInput,
            chatId = chatId,
            userId = GrowlAdSDK.getUserId(requireContext()),
            publisherId = PUBLISHER_ID
        )
    }

Next Steps

Section titled “Next Steps”