API reference

`SparrowDeskConfig`

Property	Type	Description
`domain`	`String`	Your SparrowDesk host, e.g. `yourcompany.sparrowdesk.com`
`token`	`String`	Widget token from the SparrowDesk dashboard
`debug`	`Boolean` (default `false`)	When `true`, the SDK emits diagnostic logs. Use during integration; keep `false` in release — gated calls are no-ops when disabled.

Android (Kotlin)

data class SparrowDeskConfig(
    val domain: String,
    val token: String,
    val debug: Boolean = false
)

iOS (Swift) — pass the same three values to the Swift initializer produced by the Kotlin framework.

debug logging:

Android: adb logcat -s SparrowDeskSDK:V (tag SparrowDeskSDK).
iOS: print output in the Xcode console.

`SparrowDeskSDK`

Create one instance with a SparrowDeskConfig, then attach it to a view hierarchy, call control methods, and destroy() when the screen is dismissed.

Method	Platform	Description
`attach(context, parent)`	Android	Creates the `WebView` and adds it to the `ViewGroup`.
`attach(parentView)`	iOS	Creates the `WKWebView` and adds it to the `UIView`.
`openWidget()`	both	Opens the chat widget.
`closeWidget()`	both	Closes the chat widget.
`hideWidget()`	both	Hides the launcher and the widget panel.
`onOpen(callback)`	both	Fires when the widget opens.
`onClose(callback)`	both	Fires when the widget closes.
`setTags(tags)`	both	Attaches string tags to the current session.
`setContactFields(fields)`	both	Sets contact fields (e.g. `email`, `name`, `phone`).
`setConversationFields(fields)`	both	Sets conversation-level custom fields.
`getStatus(callback)`	both	Asynchronously returns the current `WidgetStatus`.
`show()`	both	Makes the WebView container visible.
`hide()`	both	Hides the WebView container.
`destroy()`	both	Tears down the WebView and releases resources. Always call this when the hosting `Activity` / view controller is torn down.

Methods like setContactFields, setTags, and setConversationFields can be called before the widget has finished loading: commands are queued and replayed after the native bridge receives a ready signal from the page.

`WidgetStatus`

Value	Meaning
`OPEN`	Widget is open.
`CLOSED`	Widget is closed.
`UNKNOWN`	Not ready yet (e.g. still loading).

Usage examples (Kotlin)

Identify the user (before or after attach):

sdk.setContactFields(mapOf(
    "email" to "[email protected]",
    "name"  to "Jane Doe",
    "phone" to "+1234567890"
))

Session tags:

sdk.setTags(listOf("vip", "enterprise", "priority-support"))

Conversation fields:

sdk.setConversationFields(mapOf(
    "plan"   to "enterprise",
    "source" to "mobile-app"
))

Open / close callbacks (Android):

sdk.onOpen  { /* widget opened */ }
sdk.onClose { /* widget closed */ }

Query state:

sdk.getStatus { status ->
    when (status) {
        WidgetStatus.OPEN    -> { }
        WidgetStatus.CLOSED  -> { }
        WidgetStatus.UNKNOWN -> { }
    }
}

iOS: `onOpen` / `onClose` and Swift

Kotlin fun interface types export to Objective-C as protocols. Swift closures do not automatically satisfy those protocols. Wrap the handler in a small NSObject that conforms to the generated callback type, for example:

class CallbackWrapper: NSObject, SparrowDeskCallback {
    private let handler: () -> Void
    init(_ handler: @escaping () -> Void) { self.handler = handler }
    func onEvent() { handler() }
}

sdk.onOpen(callback: CallbackWrapper { print("Widget opened") })

Replace SparrowDeskCallback with the exact protocol name your Xcode build shows for the open/close callback types if it differs in your SDK version.

Lifecycle

Attach once you have a container view; open the UI when the user requests it (openWidget()).
On Android, call sdk.destroy() from onDestroy() (or the equivalent) after removing the view.
On iOS, call sdk.destroy() from deinit or when leaving the screen, matching your ownership model.

For full sample apps, build commands, and architecture notes, see the repository README.

API reference

SparrowDeskConfig

SparrowDeskSDK

WidgetStatus