# API reference (/mobile-sdk/api)

## `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)**

```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`):

```kotlin
sdk.setContactFields(mapOf(
    "email" to "user@example.com",
    "name"  to "Jane Doe",
    "phone" to "+1234567890"
))
```

**Session tags:**

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

**Conversation fields:**

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

**Open / close callbacks (Android):**

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

**Query state:**

```kotlin
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:

```swift
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](https://github.com/SparrowDesk/sparrowdesk-mobile-sdk/blob/main/README.md).