Welloo SDK - Guide d'Intégration #

SDK Flutter pour les paiements Welloo/Wave - Simple, sécurisé, plug & play

🚀 Installation en 3 étapes #

1️⃣ Ajouter la dépendance #

dependencies:
  welloo_sdk: ^0.0.51

2️⃣ Initialiser le SDK dans `main()` #

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await WellooSdk.init(); // ← OBLIGATOIRE
  
  runApp(const MyApp());
}

3️⃣ Lancer un dépôt #

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => WellooDeposit(
      packageName: 'wellooapp',
      accessToken: "VOTRE_ACCESS_TOKEN",
      refreshToken: "VOTRE_REFRESH_TOKEN",
      waitResponse: (response) {
        // Transaction terminée
        print('Status: ${response['status']}'); // SUCCEEDED | FAILED
        print('Référence: ${response['reference_transaction']}');
      },
      onError: (error) {
        print('Erreur: ${error['description']}');
      },
    ),
  ),
);

C'est tout ! Le SDK gère automatiquement :

✅ La vérification de la transaction (détection < 1s)
✅ Le retour depuis l'app Wave vers votre app
✅ Les erreurs et les cas limites

📱 Configuration Deep Links (Optionnel) #

Pour une détection instantanée (< 1 seconde), configurez les deep links :

Android - `AndroidManifest.xml` #

<activity android:name=".MainActivity" android:launchMode="singleTop">
    <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="wellooapp"/>
    </intent-filter>
</activity>

iOS - `Info.plist` #

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>wellooapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>ci.wellooapp</string>
    </dict>
</array>
<key>FlutterDeepLinkingEnabled</key>
<true/>

⚠️ Important : Le scheme wellooapp est identique pour tous les intégrateurs.

Sans deep links : Le SDK utilise uniquement le polling (vérification toutes les 5s, max 5 min). Ça marche aussi !

🔧 Configuration Backend (Wave) #

Important : Le SDK N'A PAS DE ROUTES. Il écoute juste les deep links via app_links.

Deux Options Possibles #

Option 1 : Deep Link Direct (Recommandé - Simple)

Votre backend envoie directement le custom scheme à Wave :

// Dans votre backend lors de l'appel API Wave
{
  "success_url": "wellooapp://?status=success&reference={{reference}}",
  "error_url": "wellooapp://?status=error&reference={{reference}}"
}

Avantages :

✅ Pas de serveur intermédiaire nécessaire
✅ Wave ouvre directement votre app
✅ Plus simple et plus rapide

Flux :

Wave termine paiement
  ↓
Wave ouvre "wellooapp://?status=success&reference=OP_123"
  ↓
OS ouvre votre app (retour sur l'écran SDK)
  ↓
SDK écoute via app_links → traite les données

Option 2 : Via Backend Intermédiaire (Logging/Analytics)

Si vous voulez logger ou tracker les callbacks de Wave :

// Votre backend envoie d'abord vers votre serveur
{
  "success_url": "https://votre-backend.com/wave/success",
  "error_url": "https://votre-backend.com/wave/error"
}

Votre backend doit ensuite :

// Node.js exemple
app.get('/wave/success', (req, res) => {
  const reference = req.query.reference;
  
  // 1. Logger l'événement
  logger.info('Payment success:', reference);
  
  // 2. Sauvegarder en DB
  await db.payments.update(reference, { status: 'success' });
  
  // 3. Rediriger vers l'app (OBLIGATOIRE)
  res.redirect(301, `wellooapp://?status=success&reference=${reference}`);
});

Flux :

Wave termine paiement
  ↓
Wave POST vers votre backend
  ↓
Votre backend : log + DB + redirect
  ↓
Navigateur redirige vers "wellooapp://..."
  ↓
OS ouvre votre app
  ↓
SDK écoute via app_links

⚠️ Ce que le SDK NE fait PAS #

❌ Pas de navigation vers une route (/success, /error)
❌ Pas de Navigator.push() lors du deep link
❌ Pas de recherche de route dans le routing
✅ Juste une écoute réactive via stream

L'app reste sur la même vue (écran du SDK), seules les données sont traitées.

📚 Documentation complète : Voir DEEP_LINK_NO_NAVIGATION.md

📖 Fonctionnalités Avancées #

Gestion de session utilisateur

// Enregistrer un client
final result = await WellooSdk().registerClient(
  accessToken: 'YOUR_TOKEN',
  refreshToken: 'YOUR_REFRESH',
);

// Vérifier la session
if (await WellooSdk.hasValidTokens()) {
  final client = await WellooSdk().getCurrentClient();
  print('Utilisateur: ${client.data?.nom}');
}

// Déconnexion
await WellooSdk().logout();

Double mécanisme de vérification

Le SDK combine automatiquement :

Deep Link via Streams → Détection réactive (< 1s) via deepLinkDataStream
Polling → Fallback automatique (vérification toutes les 5s)

Architecture :

Deep link reçu
  ↓
app_links.uriLinkStream
  ↓
DeepLinkService parse et émet
  ↓
deepLinkDataStream (référence + statut)
  ↓
DepositDataRemoteSource écoute
  ↓
Arrêt polling + émission transaction
  ↓
waitResponse() appelé avec résultat

Le système est 100% réactif : pas de polling du deep link, juste des streams asynchrones.

📚 Voir DEEP_LINK_STREAM.md pour l'architecture complète.

Configurations personnalisées

8 configurations prédéfinies disponibles :

Configuration	Usage
`waveConfig`	Wave CI (150x @ 2s)
`welloConfig`	Wello (60x @ 3s)
`productionConfig`	Production (60x @ 5s)
`developmentConfig`	Dev/Debug (30x @ 1s)

Voir docs/SDK_INTEGRATION.md pour plus de détails.

❓ FAQ #

Le deep link est-il obligatoire ?

Non. Sans deep link, le SDK utilise le polling (vérification toutes les 5s). Ça fonctionne parfaitement, mais la détection prend 5-30 secondes au lieu de < 1 seconde.

Le SDK navigue-t-il vers une route quand il reçoit un deep link ?

NON ! C'est une confusion fréquente. Le SDK N'A AUCUNE ROUTE.

Quand wellooapp://?status=success est ouvert :

L'OS ouvre votre app (qui était déjà sur l'écran du SDK)
Le SDK écoute via app_links.uriLinkStream
Il traite les données et appelle waitResponse()
Aucun Navigator.push() n'est exécuté

L'app reste sur la même vue (celle du SDK). Pas de navigation, juste un traitement réactif des données.

Que signifie "packageName: 'wellooapp'" ?

C'est le scheme du deep link utilisé par le SDK. Tous les intégrateurs utilisent wellooapp. Ne le confondez pas avec le package Android de votre app (ex: com.example.myapp).

Comment obtenir mes tokens d'authentification ?

Les tokens sont fournis par votre backend après authentification utilisateur. Le SDK ne gère pas l'authentification, seulement les transactions.

Puis-je tester sans backend ?

Oui ! Créez un fichier .env dans example/ avec vos tokens de test :

ACCESS_TOKEN=votre_token_test
REFRESH_TOKEN=votre_refresh_token_test

Puis lancez example/lib/main.dart.

Le polling consomme-t-il beaucoup de batterie ?

Non. Le polling ne dure que 5 minutes maximum (60 tentatives × 5s) et s'arrête dès qu'une transaction est détectée ou que l'utilisateur quitte l'écran.

📚 Documentation Complète #

SDK_INTEGRATION.md - Guide d'intégration détaillé
DEEPLINK_INTEGRATION.md - Configuration deep links
TOKEN_STORAGE_FIX.md - Architecture du stockage des tokens

🆘 Support #

Problèmes fréquents :

Tokens détruits → Vérifiez que WellooSdk.init() est appelé dans main()
Deep link ne fonctionne pas → Vérifiez la configuration AndroidManifest.xml / Info.plist
Transaction timeout → Le polling s'arrête après 5 min, utilisez checkDepositStatus() pour vérifier manuellement

Contact : Consultez les issues GitHub

📄 Licence #

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

Avec Logs Détaillés #

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

============================================================
🚀 WELLOO SDK - DOUBLE MÉCANISME ACTIF
============================================================
Configuration: Wave Config (2s, 150x)
🔄 Deep link: wellooapp://?status=...&reference=...
🔄 Polling: 5s × 60 tentatives (fallback)
Circuit Breaker: Activé
Retry Policy: Max 3 tentatives
============================================================

📦 INITIATION DÉPÔT
============================================================
🔗 Deep link détecté: OP_DEP_20251209_ABC123
⚡ Vérification immédiate via API...

✅ 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}');
}

🎨 Exemple Complet #

Voir example/lib/main.dart pour un exemple d'application complète avec :

Gestion de session utilisateur
Enregistrement client
Lancement de dépôts
Vérification manuelle de transactions
Gestion d'erreurs

🏗️ Pour les Développeurs #

Architecture du SDK

Le SDK utilise une architecture moderne :

Strategy Pattern : 3 stratégies de vérification (Polling, Deeplink, Hybrid)
Repository Pattern : Abstraction API avec AuthTokenService
Cache Pattern : Tokens en mémoire + FlutterSecureStorage isolé
Circuit Breaker Pattern : Protection contre les erreurs en cascade

lib/
├── src/
│   ├── features/
│   │   ├── authentication/   # Gestion tokens
│   │   ├── depots/          # Services dépôt
│   │   └── transactions/    # Vérification
│   ├── shared/
│   │   ├── config/          # Configurations
│   │   ├── services/        # Logger, Storage
│   │   └── deep_link_service.dart
│   └── welloo_sdk.dart
└── welloo_sdk.dart

Métriques disponibles

Le SDK expose des métriques en temps réel :

final metrics = WellooSdk().getMetrics();
print('Taux de succès: ${metrics.successRate}%');
print('Temps moyen: ${metrics.averageResponseTime}ms');
print('Deep links reçus: ${metrics.deeplinkCount}');

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 :

Scénario	Comportement	Tokens Préservés
Premier lancement	Initialisation complète	❌ (pas encore de tokens)
`registerClient()`	Enregistre tokens en cache + storage	✅
App en arrière-plan	Tokens restent en cache	✅
App fermée/rouverte	Tokens rechargés depuis storage	✅
Appels multiples `init()`	Ignorés (déjà initialisé)	✅
`init(forceReinit: true)`	Réinitialisation complète	✅ (lus depuis storage)
`logout()`	Supprime tokens	❌
`dispose()`	Nettoie ressources	✅ (persistent en storage)

✅ Bonnes Pratiques #

1. Initialisation du SDK #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // ✅ TOUJOURS initialiser le SDK dans main()
  await WellooSdk.init();
  
  runApp(const MyApp());
}

2. Utilisation du packageName #

// ✅ BON : Utiliser le scheme deep link
WellooDeposit(
  packageName: 'wellooapp', // Scheme fixe pour tous les intégrateurs
  accessToken: token,
  refreshToken: refreshToken,
)

// ❌ MAUVAIS : Utiliser le package Android
WellooDeposit(
  packageName: 'com.example.myapp', // Ne pas utiliser !
  accessToken: token,
  refreshToken: refreshToken,
)

3. Configuration Deep Links #

<!-- ✅ BON : Scheme sans host/path -->
<data android:scheme="wellooapp"/>

<!-- ❌ MAUVAIS : Avec host (cause des 404) -->
<data android:scheme="wellooapp" android:host="payment"/>

4. Format des URLs #

// ✅ BON : Format racine avec query parameters
"wellooapp://?status=success&reference=OP_DEP_..."

// ❌ MAUVAIS : Avec path (navigation vers route inexistante)
"wellooapp://home?status=success&reference=OP_DEP_..."

5. Gestion des Tokens #

// ✅ BON : Vérifier avant utilisation
if (await WellooSdk.hasValidTokens()) {
  await WellooSdk().initDeposit(context: context);
} else {
  // Demander à l'utilisateur de se connecter
}

// ✅ BON : Enregistrer après connexion
await WellooSdk().registerClient(
  accessToken: loginResponse.accessToken,
  refreshToken: loginResponse.refreshToken,
);

6. Gestion du Cycle de Vie #

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

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

7. Gestion des Erreurs #

final result = await WellooSdk().initDeposit(context: context);

switch (result.status) {
  case TransactionStatus.completed:
    // ✅ Succès - afficher confirmation
    showSuccessDialog();
    break;
  case TransactionStatus.failed:
    // ⚠️ Échec - afficher erreur avec message
    showErrorDialog(result.message);
    break;
  case TransactionStatus.canceled:
    // ℹ️ Annulé - retour simple
    Navigator.pop(context);
    break;
  case TransactionStatus.pending:
    // ⏳ En attente - afficher loader
    showLoadingDialog();
    break;
}

🆘 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

welloo_sdk 0.0.61 welloo_sdk: ^0.0.61 copied to clipboard

Metadata

Welloo SDK - Guide d'Intégration #

🚀 Installation en 3 étapes #

1️⃣ Ajouter la dépendance #

2️⃣ Initialiser le SDK dans main() #

3️⃣ Lancer un dépôt #

📱 Configuration Deep Links (Optionnel) #

Android - AndroidManifest.xml #

iOS - Info.plist #

🔧 Configuration Backend (Wave) #

Deux Options Possibles #

Option 1 : Deep Link Direct (Recommandé - Simple)

Option 2 : Via Backend Intermédiaire (Logging/Analytics)

⚠️ Ce que le SDK NE fait PAS #

📖 Fonctionnalités Avancées #

❓ FAQ #

📚 Documentation Complète #

🆘 Support #

📄 Licence #

Avec Logs Détaillés #

Vérification Manuelle #

🎨 Exemple Complet #

🏗️ Pour les Développeurs #

Flux de Données #

Gestion des Tokens #

📊 Pays Supportés #

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

✅ Bonnes Pratiques #

1. Initialisation du SDK #

2. Utilisation du packageName #

3. Configuration Deep Links #

4. Format des URLs #

5. Gestion des Tokens #

6. Gestion du Cycle de Vie #

7. Gestion des Erreurs #

🆘 Support #

📝 Changelog #

Version 0.0.51 #

Version 0.0.50 #

← Metadata

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

welloo_sdk 0.0.61
welloo_sdk: ^0.0.61 copied to clipboard

2️⃣ Initialiser le SDK dans `main()` #

Android - `AndroidManifest.xml` #

iOS - `Info.plist` #