Recording Messages

Recording messages allows Growl to build context about the conversation, enabling more relevant ad targeting. This is separate from displaying ads and should be called for every user and AI message.

Overview

The recordMessage function sends individual messages to Growl’s analytics backend. This data helps improve ad relevance and provides insights into conversation patterns.

Function Signature

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

Parameters

Parameter	Type	Description
`context`	`Context`	Android context
`role`	`MessageRole`	Either `USER` or `ASSISTANT`
`message`	`String`	The text content of the message
`chatId`	`String`	Unique identifier for the conversation
`userId`	`String`	Unique identifier for the user
`publisherId`	`String`	Your Growl Publisher ID

Returns

Returns true if the message was recorded successfully (HTTP 2xx response), false otherwise.

Message Roles

import com.withgrowl.growlandroidsdk.MessageRole

// For user messages
MessageRole.USER

// For AI/bot responses
MessageRole.ASSISTANT

Getting User ID

The SDK provides a built-in helper to generate and persist a unique user ID:

import com.withgrowl.growlandroidsdk.GrowlAdSDK

val userId = GrowlAdSDK.getUserId(context)

This generates a UUID on first call and persists it in SharedPreferences, returning the same ID on subsequent calls.

Recording User Messages

Call recordMessage when the user sends a message:

import com.withgrowl.growlandroidsdk.GrowlAdSDK
import com.withgrowl.growlandroidsdk.MessageRole

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

Recording AI Messages

Call recordMessage when the AI responds:

// After receiving AI response
lifecycleScope.launch {
    GrowlAdSDK.recordMessage(
        context = requireContext(),
        role = MessageRole.ASSISTANT,
        message = aiResponse,
        chatId = chatId,
        userId = GrowlAdSDK.getUserId(requireContext()),
        publisherId = PUBLISHER_ID
    )
}

Best Practices

Text Only: Only pass text content. Do not include images, files, or links in the message parameter.
Fire and Forget: Recording is non-blocking. You don’t need to wait for the result before continuing.
Both Directions: Record both user messages and AI responses for complete context.
Use SDK’s getUserId: Use GrowlAdSDK.getUserId(context) instead of generating your own user IDs.

Using LiveData/StateFlow Observer

If your chat is driven by a ViewModel, you can record messages in an observer:

viewModel.chatItems.observe(viewLifecycleOwner) { items ->
    adapter.submitList(items.toList())

    // Record the last message if it's new
    val lastItem = items.lastOrNull()
    if (lastItem is Message) {
        lifecycleScope.launch {
            GrowlAdSDK.recordMessage(
                context = requireContext(),
                role = lastItem.sender,
                message = lastItem.text,
                chatId = chatId,
                userId = GrowlAdSDK.getUserId(requireContext()),
                publisherId = PUBLISHER_ID
            )
        }
    }
}

Error Handling

The function returns false on failure but doesn’t throw exceptions. Errors are logged internally:

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

    if (!success) {
        // Optional: Log or handle the failure
        // Recording failures are non-critical and shouldn't block the user
    }
}