Welloo SDK

Welloo SDK est un SDK Flutter qui facilite l'intégration du service de paiement Welloo dans vos applications mobiles. Il fournit des widgets pour configurer et exécuter des paiements de manière sécurisée avec un système de vérification moderne et résilient.

✨ Fonctionnalités #

Interface Utilisateur #

• 💳 Initialisation sécurisée du SDK
• 🔗 Gestion sécurisée des transactions (dépôt, transfert)
• 📦 Intégration rapide dans n'importe quelle app Flutter
• 🧩 Compatible Android & iOS
• 🎨 Interface moderne avec animations et design responsive
• 🔄 Gestion automatique du cycle de vie avec WidgetsBindingObserver

Gestion Robuste du Cycle de Vie #

• 🔐 Système de cache intelligent : Tokens en mémoire avec synchronisation automatique
• 🔄 Réinitialisations multiples sécurisées : Support du cycle de vie complet de l'app
• ✅ Validation automatique : Vérification des tokens avant opérations critiques
• 🛡️ Protection des tokens : Cache ↔ Storage toujours synchronisés
• 🚀 Performance optimisée : Pas d'I/O répétés pour les tokens

Nouveau Système de Vérification #

• ⚡ 3 stratégies de vérification : Polling, Deeplink, Hybrid
• 🎯 8 configurations prédéfinies : Wave, Wello, Production, Development, etc.
• 🛡️ Circuit Breaker : Protection contre les cascades d'erreurs
• 🔄 Retry Policy : Retry automatique avec exponential backoff
• 📊 Métriques détaillées : Taux de succès, temps de réponse, etc.
• 📡 12 types d'events : Monitoring en temps réel
• 🔍 Logs structurés : 4 niveaux (DEBUG, INFO, WARNING, ERROR)
• ✅ Type-safe : Sealed classes avec pattern matching

🎯 Système de Vérification #

Le SDK propose 3 stratégies pour vérifier vos transactions :

Configurations Prédéfinies #

🚀 Installation #

1. Ajouter la dépendance #

flutter pub add welloo_sdk

Ou dans votre pubspec.yaml :

dependencies:
  welloo_sdk: ^0.0.51

2. Initialisation (OBLIGATOIRE) #

Le SDK doit être initialisé dans main() avant le lancement de l'app :

import 'package:flutter/material.dart';
import 'package:welloo_sdk/welloo_sdk.dart';
import 'package:welloo_sdk/src/shared/services/logger_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Configurer le logger (optionnel)
  LoggerService().configure(
    minLevel: LogLevel.debug,
    enabledInProduction: true,
  );

  // Initialize Welloo SDK
  await WellooSdk.init();

  runApp(const MyApp());
}

👩‍💻 Utilisation Basique #

Enregistrement d'un Client #

import 'package:welloo_sdk/welloo_sdk.dart';

// Enregistrer un nouveau client avec tokens
final result = await WellooSdk().registerClient(
  accessToken: 'YOUR_ACCESS_TOKEN',
  refreshToken: 'YOUR_REFRESH_TOKEN',
);

result.when(
  success: (client) {
    print('Client enregistré: ${client.nom}');
  },
  failure: (error) {
    print('Erreur: $error');
  },
);

Vérifier l'État du SDK #

// Vérifier si le SDK est initialisé
if (WellooSdk.isInitialized) {
  print('SDK prêt');
}

// Vérifier si des tokens valides sont présents
if (await WellooSdk.hasValidTokens()) {
  print('Session utilisateur active');
} else {
  print('Utilisateur doit se connecter');
}

Lancer un Dépôt #

import 'package:welloo_sdk/welloo_sdk.dart';

// Via le SDK avec contexte
final result = await WellooSdk().initDeposit(context: context);

switch (result.status) {
  case TransactionStatus.completed:
    print('Dépôt réussi: ${result.transactionId}');
    break;
  case TransactionStatus.failed:
    print('Échec: ${result.message}');
    break;
  case TransactionStatus.canceled:
    print('Annulé par l\'utilisateur');
    break;
  case TransactionStatus.pending:
    print('En attente');
    break;
}

// Ou via le widget (approche legacy)
Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => WellooDeposit(
      packageName: 'com.example.myapp',
      accessToken: "YOUR_ACCESS_TOKEN",
      refreshToken: "YOUR_REFRESH_TOKEN",
      waitResponse: (response) {
        print('📦 Réponse: $response');
        // response contient:
        // - status: "pending" | "SUCCEEDED" | "FAILED"
        // - reference_transaction: "TXN_DEP_..."
        // - description: "..."
      },
      onError: (error) {
        print('❌ Erreur: $error');
      }
    ),
  ),
);

Gestion du Cycle de Vie #

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _checkSession();
  }

  Future<void> _checkSession() async {
    // Vérifier si un utilisateur est déjà connecté
    if (await WellooSdk.hasValidTokens()) {
      final result = await WellooSdk().getCurrentClient();
      result.when(
        success: (client) => print('Utilisateur: ${client.nom}'),
        failure: (error) => print('Session expirée'),
      );
    }
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    // Le SDK gère automatiquement le cycle de vie
    // Les tokens restent en cache même en arrière-plan
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    // Disposer proprement le SDK en fin de vie
    WellooSdk.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: HomeScreen());
  }
}

Avec Logs Détaillés #

Le SDK affiche automatiquement des logs structurés dans la console :

============================================================
🚀 WELLOO SDK - NOUVEAU SYSTÈME DE VÉRIFICATION
============================================================
Configuration: Wave Config (2s, 150x)
Stratégie: hybrid
Polling: 150x @ 2s
Deeplink: Activé
Circuit Breaker: Activé
Retry Policy: Max 3 tentatives
============================================================

📦 INITIATION DÉPÔT
============================================================

✅ RÉPONSE TRANSACTION:
Status: SUCCEEDED
Reference: TXN_DEP_20251205_ABC123

Vérification Manuelle #

Vous pouvez vérifier manuellement le statut d'une transaction :

final sdk = WellooSdk();

final result = await sdk.checkDepositStatus(
  reference: 'TXN_DEP_20251204_ABC123',
);

if (result.isSuccess && result.data != null) {
  final transaction = result.data!;
  print('Status: ${transaction.status}');
} else {
  print('Error: ${result.error}');
}

⚙️ Configuration Deep Links (Optionnel) #

Pour la stratégie Hybrid ou Deeplink, configurez les deep links :

Android - android/app/src/main/AndroidManifest.xml #

<activity android:name=".MainActivity" android:launchMode="singleTop">
    <!-- Deep link avec scheme personnalisé (RECOMMANDÉ) -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        <data android:scheme="yourapp" android:host="payment"/>
    </intent-filter>
</activity>

Note : Remplacez yourapp par le nom unique de votre application.

iOS - ios/Runner/Info.plist #

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
    </dict>
</array>
<key>FlutterDeepLinkingEnabled</key>
<true/>

Configuration Backend - Simplifiée #

Nouveau format direct : Le SDK envoie maintenant directement les deep links finaux :

success_url: "yourapp://?status=success&reference={{reference}}"
error_url: "yourapp://?status=error&reference={{reference}}"

✅ Avantages :

• Pas de path = Pas d'erreur 404
• Pas de redirection backend = Plus simple
• Retour direct = L'app s'ouvre sur la vue du SDK
• Callbacks immédiats = waitResponse et onError déclenchés automatiquement

🎨 Aperçu de l'Interface #

Le SDK offre un flow en 4 étapes avec une UX moderne :

1. Sélection de l'opérateur - Logos clairs avec animations
2. Numéro de téléphone - Sélecteur de pays intégré (+225, +221, etc.)
3. Montant - Calcul automatique des frais en temps réel
4. Résumé - Bouton swipe-to-confirm pour validation sécurisée

Dépôt

🛡️ Fonctionnalités Avancées #

Gestion Robuste des Tokens #

Le SDK implémente un système sophistiqué de gestion des tokens :

• Cache intelligent : Tokens stockés en mémoire pour performance
• Synchronisation automatique : Cache ↔ SharedPreferences toujours cohérents
• Refresh automatique : Renouvellement transparent lors de l'expiration
• Réinitialisations sécurisées : Support complet du cycle de vie de l'app
• Validation : Vérification avant opérations critiques

Circuit Breaker #

Protège votre app contre les cascades d'erreurs en interrompant temporairement les requêtes après plusieurs échecs consécutifs.

Retry Policy #

Retry automatique avec exponential backoff pour les erreurs réseau temporaires.

Métriques en Temps Réel #

• ✅ Taux de succès/erreur
• ⏱️ Temps de réponse moyen
• 📞 Nombre d'appels API
• 🔗 Taux de réception des deeplinks
• ⚡ Déclenchements du circuit breaker

Logs Structurés #

4 niveaux de logs (DEBUG, INFO, WARNING, ERROR) pour un debugging facile avec export JSON/Text.

📚 Documentation Complète #

Guides d'Intégration #

• 📖 Guide d'intégration détaillé - Intégration complète avec le nouveau système de vérification
• 🔧 Gestion du Cycle de Vie - Guide complet de gestion des tokens et du cycle de vie du SDK
• 💻 Exemple complet - Application de démo avec toutes les fonctionnalités

Système de Vérification #

• 🔄 Documentation Polling - Système de polling automatique
• 🔗 Configuration Deep Links - Guide détaillé des deep links
• 🛠️ Solution 404 Deep Links - Résolution du problème 404 avec les deep links
• 📱 Deep Link - Solution Simple - Format simplifié sans path

Référence Technique #

• 📝 CHANGELOG - Historique des versions et modifications
• 🏗️ Architecture - Consultez la section ci-dessous

🔧 Architecture #

Le SDK utilise une architecture moderne et maintenable :

Patterns de Conception #

• Strategy Pattern pour les 3 stratégies de vérification
• Sealed Classes pour type-safety et pattern matching
• Circuit Breaker Pattern pour la résilience
• Observer Pattern pour le lifecycle management
• Repository Pattern pour l'abstraction API
• Dependency Injection (GetIt) pour la testabilité
• Cache Pattern pour la performance des tokens

Structure du Projet #

lib/
├── src/
│   ├── features/             # Fonctionnalités métier
│   │   ├── authentication/   # Gestion des tokens et auth
│   │   ├── transactions/     # Dépôts et transferts
│   │   └── depots/          # Services de dépôt
│   ├── shared/              # Code partagé
│   │   ├── config/          # Configurations
│   │   ├── di/              # Injection de dépendances
│   │   ├── network/         # ApiClient avec gestion tokens
│   │   ├── services/        # Services (Logger, etc.)
│   │   └── data/            # AuthTokenService avec cache
│   └── welloo_sdk.dart      # Point d'entrée public
└── welloo_sdk.dart          # Export principal

Flux de Données #

UI Layer (Widgets)
    ↓
Business Logic (BLoC/Cubit)
    ↓
Use Cases
    ↓
Repositories
    ↓
Data Sources (Remote/Local)
    ↓
ApiClient ← AuthTokenService (avec cache)
    ↓
SharedPreferences (storage persistant)

Gestion des Tokens #

registerClient(accessToken, refreshToken)
    ↓
AuthTokenService.saveTokens()
    ├─→ SharedPreferences.setString()  (storage)
    └─→ _cachedAccessToken = token     (cache)

getAccessToken()
    ├─→ Si en cache → retourne cache   (rapide)
    └─→ Sinon → lit storage → met en cache

refreshTokens()
    ├─→ Appel API refresh
    ├─→ Sauvegarde storage
    └─→ Met à jour cache immédiatement

clearTokens()
    ├─→ Supprime de storage
    └─→ Invalide cache

📊 Pays Supportés #

• 🇨🇮 Côte d'Ivoire (+225)
• 🇸🇳 Sénégal (+221)
• 🇲🇱 Mali (+223)
• 🇧🇫 Burkina Faso (+226)
• 🇧🇯 Bénin (+229)
• 🇹🇬 Togo (+228)
• 🇳🇪 Niger (+227)
• 🇬🇳 Guinée (+224)
• 🇫🇷 France (+33)

🔄 Scénarios de Cycle de Vie Supportés #

Le SDK gère parfaitement ces scénarios :

🆘 Support #

Pour toute question ou problème :

• 📝 GitHub Issues
• 📧 Email: support@finapay.net
• 🌐 Documentation: https://finapay.net

📝 Changelog #

Version 0.0.51 #

• 🔐 Gestion robuste du cycle de vie avec cache intelligent des tokens
• ✅ Validation automatique des tokens avant opérations critiques
• 🔄 Réinitialisations multiples sécurisées avec option forceReinit
• 🚀 Performance optimisée : Cache mémoire pour les tokens
• 🛡️ Synchronisation garantie : Cache ↔ Storage toujours cohérents

Version 0.0.50 #

• ✨ Nouveau système de vérification avec 3 stratégies
• 🎯 8 configurations prédéfinies (Wave, Wello, Production, etc.)
• 🛡️ Circuit Breaker et Retry Policy
• 📊 Métriques détaillées et 12 types d'events
• 🔍 Logs structurés avec 4 niveaux
• ✅ Type-safe avec sealed classes
• 🔄 Amélioration de la résilience avec stratégie Hybrid

Développé avec ❤️ par l'équipe Finapay