---
sidebar_position: 1
title: Installation
description: Install and configure the Firetell Flutter SDK for iOS & Android VoIP calling.
---

# Installation & Setup

The `firetell_flutter_sdk` package enables native iOS and Android apps to make and receive VoIP calls using WebRTC, with full support for push notifications, CallKit (iOS), and ConnectionService (Android).

- **Source:** [`firetell_flutter_sdk`](https://github.com/firetellcom/firetell-flutter-sdk)
- **Platform:** iOS 13.0+ / Android API 24+
- **Language:** Dart 3.0+, Flutter 3.10+

---

## 1. Install via Git

Add to your `pubspec.yaml`:

```yaml
dependencies:
  firetell_flutter_sdk:
    git:
      url: https://github.com/firetellcom/firetell-flutter-sdk.git
      ref: main
```

Then run:

```bash
flutter pub get
```

---

## 2. Android Setup

Add the following permissions to `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<!-- Bluetooth headset audio routing (Required for Android 12+) -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- Required for VoIP push notifications -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
```

For Firebase Cloud Messaging, follow the [Firebase Flutter setup guide](https://firebase.google.com/docs/flutter/setup) and add `google-services.json` to `android/app/`.

---

## 3. iOS Setup

Add to `ios/Runner/Info.plist`:

```xml
<key>NSMicrophoneUsageDescription</key>
<string>Firetell needs microphone access for VoIP calls</string>

<key>UIBackgroundModes</key>
<array>
  <string>voip</string>
  <string>audio</string>
  <string>fetch</string>
  <string>remote-notification</string>
</array>
```

In Xcode, enable the following capabilities:

- **Push Notifications**
- **Background Modes** → Voice over IP, Audio, AirPlay, and Picture in Picture, Background fetch, Remote notifications

For Apple VoIP push (PushKit), configure your Apple VoIP Services Certificate (`.p12` or `.p8` Auth Key) in the **Firetell Console** under *Workspace Settings → Push Notifications*. For regular FCM notifications, add your `GoogleService-Info.plist` to `ios/Runner/`.

---

## 4. Import the SDK

```dart
import 'package:firetell_flutter_sdk/firetell_flutter_sdk.dart';
```

This single import gives you access to all public classes:

| Class | Description |
|-------|-------------|
| `FiretellClient` | Main client — authentication, SSE events, call management |
| `Call` | Per-call WebRTC + WebSocket signaling |
| `CallRingParams` | Incoming call notification payload |
| `CallOptions` | Outbound call configuration |
| `Session` | Authenticated session info |
| `PushTokenService` | Register VoIP/notification push tokens |
| `CallKitHandler` | Bridge between `flutter_callkit_incoming` and SDK |
| `DeviceIdHelper` | Native device ID (iOS/Android) |
| `IceServerCache` | Local cache for workspace ICE servers |

---

## ⚠️ Security Warning

> [!WARNING]
> **NEVER hardcode your Master API Key (`sk-...`) in mobile app code.**
>
> Mobile apps can be decompiled. Embedding your master API Key gives anyone full access to your workspace.

To authenticate mobile clients safely:

1. Keep your Master API Key (`sk-...`) on your **backend server**.
2. When a user logs in, your backend generates a temporary **Agent JWT Token**.
3. Pass the JWT token to the mobile app (e.g., via your login API response).
4. Use the JWT to initialize `FiretellClient`.

For JWT generation details, see the [Client Authentication Guide](/docs/sdks/javascript/authentication) (the JWT format is the same across all SDKs).

---

## Dependencies

The SDK depends on the following packages (installed automatically):

| Package | Purpose |
|---------|---------|
| [`flutter_webrtc`](https://pub.dev/packages/flutter_webrtc) | WebRTC peer connection & media |
| [`web_socket_channel`](https://pub.dev/packages/web_socket_channel) | Per-call WebSocket signaling |
| [`http`](https://pub.dev/packages/http) | REST API & SSE stream |
| [`uuid`](https://pub.dev/packages/uuid) | Session ID generation |
| [`shared_preferences`](https://pub.dev/packages/shared_preferences) | Device ID & ICE server cache |
| [`device_info_plus`](https://pub.dev/packages/device_info_plus) | Native device ID |
| [`flutter_callkit_incoming`](https://pub.dev/packages/flutter_callkit_incoming) | CallKit (iOS) & ConnectionService (Android) UI |