Dalel AI Flutter SDK #

The official Dalel Flutter SDK that provides an AI agent that can be integrated within any Flutter app and provide personalized recommendations. This SDK enables seamless integration of Dalel's AI-powered chat bot and recommendation system into your Flutter applications.

Features #

• 🤖 AI-Powered Chat Bot: Interactive chat interface with intelligent responses
• 🎯 Personalized Recommendations: Get tailored retailer and product recommendations based on user preferences
• 📍 Location-Based Suggestions: Recommendations based on user location
• 🌍 Multi-Language Support: Built-in support for English and Arabic (RTL support included)
• 🎨 Customizable UI: Customize colors and styling to match your app's design
• 🔄 Real-Time Streaming: Real-time message streaming for better user experience
• ⚙️ User Preferences: Support for favorite retailers, blocked retailers, and interested categories
• 📱 Responsive Design: Beautiful, modern UI that works across all screen sizes

Installation #

Add dalel_ai_flutter_sdk to your pubspec.yaml file:

dependencies:
  dalel_ai_flutter_sdk: ^1.0.0

Then run:

flutter pub get

Setup #

1. Initialize the SDK #

Before using the SDK, you need to configure it with your API credentials. This should be done early in your app lifecycle, typically in your main() function:

import 'package:dalel_ai_flutter_sdk/dalel_ai_flutter_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Configure the SDK
  DalelAICore.configure(
    DalelAIConfig(
      apiKey: 'your-api-key-here',
      baseUrl: 'https://your-dalel-ai-service.com',
      baseImageUrl: 'https://your-image-storage-url.com/s3/storage',
    ),
  );
  
  runApp(MyApp());
}

2. Configure User Information #

Set the logged in user information to enable personalized recommendations:

DalelAICore.instance.setCurrentUser(
  DalelUserConfig(
    id: 'user-123',
    name: 'John Doe',
    location: DalelUserLocation(
      latitude: 24.697015,
      longitude: 46.682108,
    ),
    favoriteRetailerIds: ['1', '2', '3'],
    blockedRetailerIds: ['4', '5'],
    interestedCategoryIds: ['7', '8', '9'],
  ),
);

3. Setup Localization #

Add the localization delegates to your MaterialApp to support the SDK's supported languages:

import 'package:dalel_ai_flutter_sdk/l10n/index.dart';

MaterialApp(
  localizationsDelegates: [
    // Other localization delegates
    DalelLocalizations.delegate,
    ],
  supportedLocales: [
    const Locale('en'),
    const Locale('ar'),
  ],
  // ... other properties
)

Currently, only English and Arabic are supported.

Usage #

Basic Integration #

The simplest way to integrate the chat bot is to use the DalelChatBotPage widget:

import 'package:dalel_ai_flutter_sdk/dalel_ai_flutter_sdk.dart';
import 'package:flutter/material.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: DalelChatBotPage(
        onRecommendationSelected: (retailerId) {
          // Handle recommendation selection
          // Navigate to retailer details page
          Navigator.push(
            context,
            MaterialPageRoute(
              builder: (context) => RetailerDetailsPage(retailerId: retailerId),
            ),
          );
        },
      ),
    );
  }
}

This page is a simple StatelessWidget that can be used within any navigation stack. It will display the chat bot interface and handle the recommendation selection by calling the onRecommendationSelected callback.

It can be used within any navigation stack.

Example using GoRouter:

GoRouter(
  routes: [
    GoRoute(path: '/recommendation-agent', builder: (context, state) => DalelChatBotPage(
        onRecommendationSelected: (retailerId) {
          // Handle recommendation selection
          // Navigate to retailer details page
          Navigator.push(
            context,
            MaterialPageRoute(
              builder: (context) => RetailerDetailsPage(retailerId: retailerId),
            ),
          );
        },
      )),
  ],
);

Example using Navigator.push:

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => DalelChatBotPage(
      onRecommendationSelected: (retailerId) {
        // Handle recommendation selection
        // Navigate to retailer details page
        Navigator.push(
          context,
          MaterialPageRoute(
            builder: (context) => RetailerDetailsPage(retailerId: retailerId),
          ),
        );
      },
    ),
  ),
);

Example using GetX:

Get.to(() => DalelChatBotPage(
  onRecommendationSelected: (retailerId) {
    // Handle recommendation selection
    // Navigate to retailer details page
    Get.to(() => RetailerDetailsPage(retailerId: retailerId));
  },
));

Customization #

You can customize the primary color of the chat bot:

DalelChatBotPage(
  primaryColor: Colors.blue, // Custom primary color
  onRecommendationSelected: (retailerId) {
    // Handle selection
  },
)

Updating User Information #

You can update user information at any time:

// Update user location
DalelAICore.instance.setCurrentUserLocation(
  DalelUserLocation(
    latitude: 25.2048,
    longitude: 55.2708,
  ),
);

// Update favorite retailers
DalelAICore.instance.setCurrentUserFavoriteRetailerIds(['1', '2', '3']);

// Update blocked retailers
DalelAICore.instance.setCurrentUserBlockedRetailerIds(['4', '5']);

// Update favorite categories
DalelAICore.instance.setCurrentUserInterestedCategoryIds(['7', '8', '9']);

API Reference #

DalelAICore #

The main class for SDK configuration and user management.

Methods

• static void configure(DalelAIConfig config): Initialize the SDK with configuration. Must be called before using any SDK features.
• static DalelAICore get instance: Get the singleton instance of DalelAICore.
• void setCurrentUser(DalelUserConfig user): Set the current user configuration.
• void setCurrentUserLocation(DalelUserLocation location): Update the current user's location.
• void setCurrentUserFavoriteRetailerIds(List<String> favoriteRetailerIds): Update favorite retailer IDs.
• void setCurrentUserBlockedRetailerIds(List<String> blockedRetailerIds): Update blocked retailer IDs.
• void setCurrentUserInterestedCategoryIds(List<String> interestedCategoryIds): Update interested category IDs.

Properties

• DalelAIConfig get config: Get the current SDK configuration.
• DalelUserConfig get currentUser: Get the current user configuration.

DalelAIConfig #

Configuration class for SDK initialization.

DalelAIConfig({
  required String apiKey,        // Your API key
  required String baseUrl,       // Base URL for API requests
  required String baseImageUrl,  // Base URL for images
})

DalelUserConfig #

User configuration class for personalization.

DalelUserConfig({
  required String id,                              // User ID
  required String name,                            // User name
  DalelUserLocation? location,                      // User location (optional)
  List<String>? blockedRetailerIds,                // Blocked retailer IDs (optional)
  List<String>? favoriteRetailerIds,               // Favorite retailer IDs (optional)
  List<String>? interestedCategoryIds,            // Interested category IDs (optional)
})

DalelUserLocation #

User location model.

DalelUserLocation({
  required num latitude,
  required num longitude,
})

DalelChatBotPage #

The main chat bot page widget.

DalelChatBotPage({
  required void Function(String retailerId) onRecommendationSelected,
  Color primaryColor = ColorName.defaultPrimaryColor,
  Key? key,
})

Parameters

• onRecommendationSelected: Required callback function that is called when a user selects a recommendation. Receives the retailerId as a parameter.
• primaryColor: Optional primary color for the chat bot UI. Defaults to #00CE8B.

Complete Example #

Here's a complete example showing full integration:

import 'package:dalel_ai_flutter_sdk/dalel_ai_flutter_sdk.dart';
import 'package:dalel_ai_flutter_sdk/l10n/index.dart';
import 'package:flutter/material.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Configure SDK
  DalelAICore.configure(
    DalelAIConfig(
      apiKey: 'your-api-key-here',
      baseUrl: 'https://your-dalel-ai-service.com',
      baseImageUrl: 'https://your-image-storage-url.com/s3/storage',
    ),
  );
  
  // Set user information
  DalelAICore.instance.setCurrentUser(
    DalelUserConfig(
      id: 'user-123',
      name: 'John Doe',
      location: DalelUserLocation(
        latitude: 24.697015,
        longitude: 46.682108,
      ),
      favoriteRetailerIds: ['1', '2', '3'],
      blockedRetailerIds: ['4', '5'],
      interestedCategoryIds: ['7', '8', '9'],
    ),
  );
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Dalel AI Demo',
      localizationsDelegates: DalelLocalizations.localizationsDelegates,
      supportedLocales: [
        const Locale('en'),
        const Locale('ar'),
      ],
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: DalelChatBotPage(
        primaryColor: Colors.deepPurple,
        onRecommendationSelected: (retailerId) {
          // Navigate to retailer details
          Navigator.push(
            context,
            MaterialPageRoute(
              builder: (context) => RetailerDetailsPage(retailerId: retailerId),
            ),
          );
        },
      ),
    );
  }
}

class RetailerDetailsPage extends StatelessWidget {
  final String retailerId;
  
  const RetailerDetailsPage({super.key, required this.retailerId});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Retailer Details')),
      body: Center(
        child: Text('Retailer ID: $retailerId'),
      ),
    );
  }
}

Requirements #

• Flutter SDK: >=1.17.0
• Dart SDK: ^3.9.2

Localization #

The SDK supports the following languages:

• English (en)
• Arabic (ar) - with RTL support

To use localizations, make sure to add the DalelLocalizations.localizationsDelegates to your MaterialApp as shown in the examples above.

Security Notes #

• Never commit your API key to version control. Use environment variables or secure storage.
• Keep your API key secure and do not expose it in client-side code if possible.
• The SDK handles authentication automatically using the provided API key.

Troubleshooting #

SDK Not Initialized Error #

If you see an error about the SDK not being initialized, make sure you call DalelAICore.configure() before using any SDK features:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  DalelAICore.configure(/* your config */);
  runApp(MyApp());
}

User Not Available Error #

If you see an error about user not being available, make sure you call setCurrentUser() before using the chat bot:

DalelAICore.instance.setCurrentUser(/* your user config */);

Additional Resources #

• Dalel Website
• Pub.dev Package

Support #

For issues, questions, or contributions, please visit our GitHub repository or contact support at [email protected].