Brand Concierge API reference (Android)

Managed Integration

The SDK manages the chat lifecycle. Provide a trigger UI element — the SDK shows it when the extension is ready and opens the chat as a full-screen dialog when the trigger is invoked.

Jetpack Compose

Syntax

@Composable
fun ConciergeChat(
    modifier: Modifier = Modifier,
    viewModel: ConciergeChatViewModel,
    surfaces: List<String>? = null,
    handleLink: LinkHandler? = null,
    content: @Composable (showChat: () -> Unit) -> Unit
)

Parameters

• viewModel required - A ConciergeChatViewModel instance. Obtain via viewModel<ConciergeChatViewModel>().
• surfaces - Surface identifiers sent to the Brand Concierge server.
• modifier - Optional Modifier to apply to the composable.
• handleLink - Optional LinkHandler callback. Return true to claim the URL; return false for default behavior.
• content required - Composable lambda receiving a showChat function. Call showChat() to open the chat.

Example

@Composable
fun MyScreen() {
    val viewModel = viewModel<ConciergeChatViewModel>()

    ConciergeChat(
        viewModel = viewModel,
        surfaces = listOf("web://example.com/your-surface.html")
    ) { showChat ->
        MyTriggerButton(onClick = { showChat() })
    }
}

XML/Views

Syntax

fun bind(
    lifecycleOwner: LifecycleOwner,
    viewModelStoreOwner: ViewModelStoreOwner,
    surfaces: List<String>? = null,
    theme: ConciergeThemeData? = null,
    handleLink: ((String) -> Boolean)? = null,
    triggerView: View
)

Parameters

• lifecycleOwner required - The LifecycleOwner (typically your Activity or Fragment).
• viewModelStoreOwner required - The ViewModelStoreOwner (typically your Activity or Fragment).
• surfaces - Surface identifiers sent to the Brand Concierge server.
• theme - Optional ConciergeThemeData to apply to the chat UI.
• handleLink - Optional callback. Return true to claim the URL; return false for default behavior.
• triggerView required - The View that launches the chat when clicked.

Example

val chatView = findViewById<ConciergeChatView>(R.id.concierge_chat)
val triggerButton = Button(this).apply { text = "Chat" }

chatView.bind(
    lifecycleOwner = this,
    viewModelStoreOwner = this,
    surfaces = listOf("web://example.com/your-surface.html"),
    triggerView = triggerButton
)

Custom Integration

Embed the chat interface directly into your screen and manage its lifecycle yourself. Use this for dedicated chat screens or custom layouts where you control when chat appears and handle dismissal.

Jetpack Compose

Syntax

@Composable
fun ConciergeChat(
    viewModel: ConciergeChatViewModel,
    onClose: () -> Unit,
    modifier: Modifier = Modifier,
    handleLink: LinkHandler? = null
)

Parameters

• viewModel required - A ConciergeChatViewModel instance. Obtain via viewModel<ConciergeChatViewModel>().
• onClose required - Callback invoked when the user dismisses the chat (back press, close button, or gesture).
• modifier - Optional Modifier to apply to the composable.
• handleLink - Optional LinkHandler callback. Return true to claim the URL; return false for default behavior.

Example

@Composable
fun YourChatScreen() {
    val viewModel = viewModel<ConciergeChatViewModel>()
    val conciergeState by ConciergeStateRepository.instance.state.collectAsStateWithLifecycle()
    val surfaces = listOf("web://example.com/your-surface.html")

    ConciergeStateRepository.instance.setSessionSurfaces(surfaces)

    val ready = conciergeState.configurationReady &&
        conciergeState.experienceCloudId != null &&
        conciergeState.surfaces.isNotEmpty()

    if (ready) {
        ConciergeChat(
            viewModel = viewModel,
            onClose = { /* navigate back */ }
        )
    }
}

XML/Views

Syntax

fun bind(
    lifecycleOwner: LifecycleOwner,
    viewModelStoreOwner: ViewModelStoreOwner,
    surfaces: List<String>? = null,
    theme: ConciergeThemeData? = null,
    handleLink: ((String) -> Boolean)? = null,
    onClose: () -> Unit
)

Parameters

• lifecycleOwner required - The LifecycleOwner (typically your Activity or Fragment).
• viewModelStoreOwner required - The ViewModelStoreOwner (typically your Activity or Fragment).
• surfaces - Surface identifiers sent to the Brand Concierge server.
• theme - Optional ConciergeThemeData to apply to the chat UI.
• handleLink - Optional callback. Return true to claim the URL; return false for default behavior.
• onClose required - Callback invoked when the user dismisses the chat.

Example

val chatView = findViewById<ConciergeChatView>(R.id.concierge_chat)

chatView.bind(
    lifecycleOwner = this,
    viewModelStoreOwner = this,
    surfaces = listOf("web://example.com/your-surface.html"),
    onClose = { finish() }
)

Concierge.setAuthTokenProvider

Registers a ConciergeAuthTokenProvider that supplies an app-minted authentication token, attached to every chat and feedback request until cleared. Pass null to clear a previously registered provider.

Syntax

@JvmStatic
@JvmOverloads
fun setAuthTokenProvider(
    provider: ConciergeAuthTokenProvider?,
    timeoutMillis: Long = 3000L
)

Parameters

• provider required - A ConciergeAuthTokenProvider instance, or null to clear a previously registered provider.
• timeoutMillis - How long to wait for provider.provideToken() before sending the turn without a token. Defaults to 3000 (3 seconds); out-of-bounds values are clamped rather than rejected.

Example

Concierge.setAuthTokenProvider(
    ConciergeAuthTokenProvider { myAuthTokenCache.getCurrentToken() },
    timeoutMillis = 5000L
)

ConciergeAuthTokenProvider

A functional interface that supplies the app-minted authentication token attached to each conversation turn (chat and feedback). Register an implementation with Concierge.setAuthTokenProvider.

Syntax

fun interface ConciergeAuthTokenProvider {
    fun provideToken(): String?
}

Parameters

• provideToken required - Called immediately before building each turn's request. Return the current opaque, app-minted token, or null to send the turn without one. Invoked on a background thread and may block briefly to refresh the token; the SDK bounds the wait via timeoutMillis.

ConciergeThemeLoader.load

Loads a ConciergeThemeData from a JSON file in the app's assets directory. Returns null if the file cannot be found or parsed.

Syntax

@JvmStatic fun load(context: Context, filename: String): ConciergeThemeData?

Parameters

• context required - An Android Context used to access the assets directory.
• filename required - The filename of the JSON theme file (including the .json extension).

Example

val theme = ConciergeThemeLoader.load(context, "my-theme.json")
    ?: ConciergeThemeLoader.default()

ConciergeThemeLoader.default

Returns the built-in default ConciergeThemeData.

Syntax

@JvmStatic fun default(): ConciergeThemeData

Example

val theme = ConciergeThemeLoader.default()