|
1 | | -# chative-flutter-sdk |
| 1 | +# [Chative.IO](https://chative.io/) Widget for Flutter |
| 2 | + |
| 3 | +[Chative.IO](https://chative.io/) Widget is a Flutter package that provides an easy-to-use chat widget for your mobile applications. It allows you to integrate a customizable chat interface with minimal setup. |
| 4 | + |
| 5 | +[](https://img.shields.io/pub/v/chative_sdk.svg) |
| 6 | + |
| 7 | +## Requirements |
| 8 | + |
| 9 | +- Dart sdk: ">=3.0.0" |
| 10 | +- Flutter: ">=3.x" |
| 11 | +- Android: `minSdkVersion >= 19`, `compileSdk >= 34`, [AGP](https://developer.android.com/build/releases/gradle-plugin) version `>= 7.3.0` (use [Android Studio - Android Gradle plugin Upgrade Assistant](https://developer.android.com/build/agp-upgrade-assistant) for help), support for `androidx` (see [AndroidX Migration](https://flutter.dev/docs/development/androidx-migration) to migrate an existing app) |
| 12 | +- iOS 12.0+: `--ios-language swift`, Xcode version `>= 15.0` |
| 13 | + |
| 14 | +## Features |
| 15 | + |
| 16 | +- **Customizable Chat Interface**: Tailor the chat widget to match your app's design. |
| 17 | +- **Programmatic Show/Hide**: Easily display or hide the chat widget as needed. |
| 18 | +- **Custom Header Components**: Add custom headers to enhance the chat experience. |
| 19 | +- **User Information Integration**: Populate user details into live chat for personalized interactions. |
| 20 | +- **Adjustable Insets**: Customize insets to accommodate different device sizes. |
| 21 | +- **Dart Support**: Fully compatible with Dart for seamless integration. |
| 22 | + |
| 23 | +## Screenshot |
| 24 | + |
| 25 | +<img src="https://raw.githubusercontent.com/botstar/chative-flutter-sdk/HEAD/screenshot/screenshot.png" alt="screenshot" width="350"> |
| 26 | + |
| 27 | +## Installation |
| 28 | + |
| 29 | +Add the `chative_sdk` package to your `pubspec.yaml`: |
| 30 | + |
| 31 | +```yaml |
| 32 | +dependencies: |
| 33 | + flutter: |
| 34 | + sdk: flutter |
| 35 | + chative_sdk: ^x.x.x |
| 36 | +``` |
| 37 | +
|
| 38 | +Then, run: |
| 39 | +
|
| 40 | +```zsh |
| 41 | +flutter pub get --no-example |
| 42 | +``` |
| 43 | + |
| 44 | +> **Note**: This library already includes [`webview_flutter`](https://pub.dev/packages/webview_flutter). Ensure you follow the [webview_flutter configuration instructions](https://pub.dev/packages/webview_flutter/install) for your platform. |
| 45 | +
|
| 46 | +## Usage |
| 47 | + |
| 48 | +For more detailed examples, please refer to the [example](./example/lib/main.dart) directory. |
| 49 | + |
| 50 | + |
| 51 | +Here's a concise example of how to integrate the `ChativeWidget` into your Flutter application on a single screen: |
| 52 | + |
| 53 | +```dart |
| 54 | +import 'package:flutter/material.dart'; |
| 55 | +import 'package:chative_sdk/chative_sdk.dart'; |
| 56 | +
|
| 57 | +void main() { |
| 58 | + runApp(const MyApp()); |
| 59 | +} |
| 60 | +
|
| 61 | +class MyApp extends StatelessWidget { |
| 62 | + const MyApp({super.key}); |
| 63 | +
|
| 64 | + @override |
| 65 | + Widget build(BuildContext context) { |
| 66 | + return MaterialApp( |
| 67 | + title: 'Chative.IO Flutter Demo', |
| 68 | + theme: ThemeData( |
| 69 | + colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple), |
| 70 | + useMaterial3: true, |
| 71 | + ), |
| 72 | + home: const HomeScreen(), |
| 73 | + ); |
| 74 | + } |
| 75 | +} |
| 76 | +
|
| 77 | +class HomeScreen extends StatefulWidget { |
| 78 | + const HomeScreen({super.key}); |
| 79 | +
|
| 80 | + @override |
| 81 | + State<HomeScreen> createState() => _HomeScreenState(); |
| 82 | +} |
| 83 | +
|
| 84 | +class _HomeScreenState extends State<HomeScreen> { |
| 85 | + final ChativeWidgetController _controller = ChativeWidgetController(); |
| 86 | +
|
| 87 | + final String channelId = 'YOUR_CHANNEL_ID'; |
| 88 | + final Map<String, dynamic> user = { |
| 89 | + 'user_id': 'UNIQUE_USER_ID', |
| 90 | + 'user': { |
| 91 | + |
| 92 | + 'first_name': 'Chative', |
| 93 | + 'last_name': 'User', |
| 94 | + 'phone': '1234567890', |
| 95 | + 'custom_field': 'CUSTOMER_FIELD_VALUE' |
| 96 | + }, |
| 97 | + }; |
| 98 | +
|
| 99 | + void _showChat() { |
| 100 | + _controller.show(); |
| 101 | + } |
| 102 | +
|
| 103 | + void _clearData() { |
| 104 | + _controller.clearData(); |
| 105 | + } |
| 106 | +
|
| 107 | + @override |
| 108 | + Widget build(BuildContext context) { |
| 109 | + return Scaffold( |
| 110 | + appBar: AppBar( |
| 111 | + title: const Text('Chative.IO Flutter Demo'), |
| 112 | + ), |
| 113 | + body: Stack( |
| 114 | + children: [ |
| 115 | + Center( |
| 116 | + child: Column( |
| 117 | + mainAxisSize: MainAxisSize.min, |
| 118 | + children: [ |
| 119 | + ElevatedButton( |
| 120 | + onPressed: _showChat, |
| 121 | + child: Text('Show Chat Widget'), |
| 122 | + ), |
| 123 | + const SizedBox(height: 20), |
| 124 | + ElevatedButton( |
| 125 | + onPressed: _clearData, |
| 126 | + child: Text('Clear Data'), |
| 127 | + ), |
| 128 | + ], |
| 129 | + )), |
| 130 | + ChativeWidget( |
| 131 | + channelId: channelId, |
| 132 | + controller: _controller, |
| 133 | + user: user, |
| 134 | + insetTop: 50, |
| 135 | + // insetBottom: 50, |
| 136 | + onClosed: () { |
| 137 | + print('Chat widget closed'); |
| 138 | + }, |
| 139 | + onLoaded: () { |
| 140 | + print('Chat widget loaded'); |
| 141 | + }, |
| 142 | + onNewMessage: (message) { |
| 143 | + print('New message received: $message'); |
| 144 | + }, |
| 145 | + onError: (message) { |
| 146 | + print('Error: $message'); |
| 147 | + }, |
| 148 | + ), |
| 149 | + ], |
| 150 | + ), |
| 151 | + ); |
| 152 | + } |
| 153 | +} |
| 154 | +``` |
| 155 | + |
| 156 | +### Explanation |
| 157 | + |
| 158 | +1. **Import Packages**: |
| 159 | + Import the necessary packages, including `chative_sdk`. |
| 160 | + |
| 161 | +2. **Initialize the App**: |
| 162 | + The `MyApp` class sets up the `MaterialApp` with a `HomeScreen` as the home. |
| 163 | + |
| 164 | +3. **Create the Chat Screen**: |
| 165 | + - **Controller Initialization**: |
| 166 | + Instantiate `ChativeWidgetController` to manage the chat widget's state. |
| 167 | + |
| 168 | + - **User Information**: |
| 169 | + Define a `user` map with necessary user details. |
| 170 | + |
| 171 | + - **Show Chat Widget**: |
| 172 | + An `ElevatedButton` triggers the `show()` method on the controller to display the chat widget. |
| 173 | + |
| 174 | + - **ChativeWidget Configuration**: |
| 175 | + The `ChativeWidget` is placed within a `Stack` to overlay it on top of the main content. Configure properties like `channelId`, `user`, `insetTop`, and callback functions to handle different states and events. |
| 176 | + |
| 177 | +## Properties |
| 178 | + |
| 179 | +| Property | Type | Required | Description | |
| 180 | +|------------------------|------------------------|----------|-------------| |
| 181 | +| `channelId` | `String` | Yes | The ID of the chat channel. | |
| 182 | +| `user` | `Map<String, dynamic>` | No | Information about the user, used for booting into live chat. | |
| 183 | +| `headerWidget` | `Widget` | No | Custom header component. | |
| 184 | +| `containerDecoration` | `BoxDecoration` | No | Custom decoration for the chat container. | |
| 185 | +| `insetTop` | `double` | No | Top inset (default: 20). | |
| 186 | +| `insetBottom` | `double` | No | Bottom inset (default: 20). | |
| 187 | +| `onClosed` | `VoidCallback` | No | Callback when the widget is closed. | |
| 188 | +| `onLoaded` | `VoidCallback` | No | Callback when the widget is loaded. | |
| 189 | +| `onNewMessage` | `Function(dynamic)` | No | Callback when a new message is received. | |
| 190 | +| `onError` | `Function(String)` | No | Callback when an error occurs. | |
| 191 | + |
| 192 | +## Methods |
| 193 | + |
| 194 | +The following methods are available via the `ChativeWidgetController`: |
| 195 | + |
| 196 | +- **`show()`**: Display the chat widget. |
| 197 | +- **`hide()`**: Hide the chat widget. |
| 198 | +- **`injectJavascript(String script)`**: Inject custom JavaScript into the chat widget. |
| 199 | +- **`reload()`**: Reload the chat widget. |
| 200 | +- **`clearData()`**: Clear data (localStorage) the chat widget |
| 201 | + |
| 202 | +### Example |
| 203 | + |
| 204 | +```dart |
| 205 | +// To show the chat widget |
| 206 | +_controller.show(); |
| 207 | +
|
| 208 | +// To hide the chat widget |
| 209 | +_controller.hide(); |
| 210 | +
|
| 211 | +// To reload the chat widget |
| 212 | +await _controller.reload(); |
| 213 | +``` |
| 214 | + |
| 215 | +## Customization |
| 216 | + |
| 217 | +You can customize the appearance of the widget by providing a custom header component and container decoration: |
| 218 | + |
| 219 | +```dart |
| 220 | +ChativeWidget( |
| 221 | + controller: _controller, |
| 222 | + channelId: "your-channel-id", |
| 223 | + headerWidget: YourCustomHeader(), |
| 224 | + containerDecoration: BoxDecoration( |
| 225 | + color: Colors.grey, |
| 226 | + borderRadius: BorderRadius.circular(10), |
| 227 | + ), |
| 228 | +) |
| 229 | +``` |
| 230 | + |
| 231 | +### Custom Header Example |
| 232 | + |
| 233 | +```dart |
| 234 | +class YourCustomHeader extends StatelessWidget { |
| 235 | + @override |
| 236 | + Widget build(BuildContext context) { |
| 237 | + return Container( |
| 238 | + color: Colors.blue, |
| 239 | + height: 50, |
| 240 | + child: Center( |
| 241 | + child: Text( |
| 242 | + 'Chative Widget Header', |
| 243 | + style: TextStyle( |
| 244 | + color: Colors.white, |
| 245 | + fontSize: 20, |
| 246 | + ), |
| 247 | + ), |
| 248 | + ), |
| 249 | + ); |
| 250 | + } |
| 251 | +} |
| 252 | +``` |
| 253 | + |
| 254 | +## User Map Structure |
| 255 | + |
| 256 | +| Key | Type | Required | Description | |
| 257 | +|----------------------|----------|----------|-------------| |
| 258 | +| `user_id` | `String` | Yes | A unique identifier for the user. Used to track the user's session in the chat. | |
| 259 | +| `user.email` | `String` | No | The user's email address. Optional, but recommended for better user identification. | |
| 260 | +| `user.first_name` | `String` | No | The user's first name. Optional, useful for personalized interactions. | |
| 261 | +| `user.last_name` | `String` | No | The user's last name. Optional, useful for personalized interactions. | |
| 262 | +| `user.phone` | `String` | No | The user's phone number. Optional, can be used for follow-up contact. | |
| 263 | +| `user.[key: string]` | `dynamic`| No | Any additional information about the user, represented as key-value pairs. Useful for custom data. | |
| 264 | + |
| 265 | +## License |
| 266 | + |
| 267 | +[MIT License](LICENSE) |
| 268 | + |
| 269 | +## Support |
| 270 | + |
| 271 | +If you encounter any issues or have questions, please [file an issue](https://github.com/botstar/chative-flutter-sdk/issues) on the GitHub repository. |
0 commit comments