ProvisCommerce AI Flutter SDK #

A comprehensive Flutter SDK for integrating the ProvisCommerce AI Chatbot into your mobile applications with advanced context support such as user data, product data, location awareness, floating chat access, and full-screen chat mode.

Features #

• Easy SDK initialization using API key (hash)
• Automatic chatbot settings and theme loading from server
• Pre-built and customizable chat UI
• Programmatic message sending and receiving
• Dynamic theme and color support
• Chat history handling
• Error handling and loading states
• Optional user location support (coordinates and address)
• Optional user, product, and cart context injection
• Floating Action Button (FAB) chatbot
• Full-screen chatbot mode
• Built-in close handling

Installation #

Add this to your pubspec.yaml file:

dependencies:
  proviscommerce_ai_flutter_sdk: ^0.0.1

Then run:

flutter pub get

Quick Start #

1. Initialize the SDK #

import 'package:proviscommerce_ai_flutter_sdk/proviscommerce_ai_flutter_sdk.dart';

await PCAIChatbot.instance.init(
  apiKey: "YOUR_API_KEY_HASH", // Replace with your actual API key
  baseUrl: "https://admin.proviscommerce.ai", // optional
);

Initialization Result Handling

final result = await PCAIChatbot.instance.init(apiKey: apiKey);

if (result.success) {
  print("SDK initialized successfully");
} else {
  print("Initialization failed: ${result.error}");
}

2. Load the Chatbot UI #

Default Embedded View

Widget chatWidget = PCAIChatbot.instance.loadView();

Custom Styled View

Widget customChatWidget = PCAIChatbot.instance.loadView(
  height: 400,
  width: double.infinity,
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(12),
    border: Border.all(color: Colors.grey),
  ),
);

Handle Close Event

PCAIChatbot.instance.loadView(
  onClose: () {
    Navigator.pop(context);
  },
);

3. Full-Screen Chatbot Mode with Context #

You can optionally pass userInfo and locationInfo to the full-screen chatbot.

Navigator.of(context).push(
  MaterialPageRoute(
    fullscreenDialog: true,
    builder: (_) => FullScreenChatbotView(
      userInfo: userInfo,           // optional
      locationInfo: locationInfo,   // optional
    ),
  ),
);

Full-Screen Chatbot View Example

class FullScreenChatbotView extends StatelessWidget {
  final Map<String, dynamic>? userInfo;
  final Map<String, dynamic>? locationInfo;

  const FullScreenChatbotView({
    super.key,
    this.userInfo,
    this.locationInfo,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: PCAIChatbot.instance.loadView(
          onClose: () => Navigator.of(context).pop(),
          userInfo: userInfo,
          locationInfo: locationInfo,
        ),
      ),
    );
  }
}

The chatbot automatically applies server-configured theme colors, including status bar styling.

4. Floating Chatbot Button (FAB) #

Add a persistent floating chatbot button across your app. All parameters below are optional.

floatingActionButton: PCAIChatbotFab(
  screenName: "product_details", // optional
  userInfo: {
    "userId": 1,
    "name": "John Doe",
    "productId": "SKU12345",
    "productName": "Wireless Headphones",
    "price": 99.99,
    "cart": {
      "itemsCount": 2,
      "totalAmount": 149.99
    },
    "language": "en",
    "currency": "USD",
  }, // optional
  locationInfo: locationInfo, // optional
),

Minimal usage:

floatingActionButton: PCAIChatbotFab(),

5. User Location Support (Optional) #

You may provide location data to enhance chatbot responses.

Map<String, dynamic> locationInfo = {
  "latitude": 28.6139,
  "longitude": 77.2090,
  "accuracy": 15,
  "address": {
    "street": "Connaught Place",
    "locality": "New Delhi",
    "country": "India",
    "postalCode": "110001"
  }
};

Location data is optional and can be omitted entirely.

6. Send Messages Programmatically #

final response = await PCAIChatbot.instance.sendMessage(
  "Hello, I need help with my order",
  metadata: {
    "source": "checkout_page" // optional
  },
);

if (response.success) {
  print(response.data?.response);
} else {
  print(response.error);
}

API Reference #

Core Methods #

Context Parameters #

All context parameters are optional.

userInfo (Map<String, dynamic>) #

Provides user, product, cart, or application-specific context to the chatbot.

locationInfo (Map<String, dynamic>) #

Provides GPS coordinates and structured address data.

screenName (String) #

Indicates the current application screen context such as home, checkout, or product_details.

Example Application #

A complete working example is available in the /example folder demonstrating:

• SDK initialization
• Location permissions and geocoding
• Floating chatbot button
• Full-screen chatbot view
• Optional user and product context injection

API Methods Summary #

1. PCAIChatbot.instance.init(apiKey: "hash") Initialize the SDK

2. PCAIChatbot.instance.loadView() Display the chatbot UI

3. PCAIChatbot.instance.sendMessage(message) Send messages programmatically

Security Notes #

• Do not hard-code API keys in production applications
• Use secure storage or environment-based configuration

License #

This project is licensed under the MIT License. See the LICENSE file for details.