Flutter GB In-App Purchases #

A comprehensive Flutter package for handling in-app purchases using the BLoC pattern with Geekbears Stack Base. This package provides a robust, platform-agnostic solution for managing consumables, non-consumables, and subscription products across iOS and Android.

Features #

• 🏗️ Clean Architecture: Built with BLoC pattern and dependency injection
• 📱 Cross-Platform: Full support for iOS (StoreKit) and Android (Google Play)
• 🔄 Product Types: Support for consumables, non-consumables, and subscriptions
• 🛡️ Transaction Verification: Built-in server-side verification with customizable endpoints
• 🔄 Subscription Management: Handle subscription upgrades, downgrades, and changes
• 📊 Real-time Updates: Stream-based transaction monitoring
• 🔧 Configurable: Highly customizable configuration options
• 🧪 Testable: Built with testing in mind using dependency injection

Supported Platforms #

• ✅ iOS (StoreKit)
• ✅ Android (Google Play)

Supported Product Types #

• Consumables: Products that can be purchased multiple times (coins, lives, etc.)
• Non-Consumables: One-time purchases (premium features, remove ads)
• Renewable Subscriptions: Auto-renewing subscriptions
• Non-Renewable Subscriptions: Time-limited subscriptions

Getting Started #

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_gb_in_app_purchases: ^1.0.0

Prerequisites #

• Flutter SDK >= 3.35.0
• Dart SDK >= 3.9.0
• iOS 14.0+ / Android API 21+

iOS Setup #

1. Configure your app in App Store Connect
2. Add your product identifiers
3. Ensure your app is signed with a valid provisioning profile

Android Setup #

1. Configure your app in Google Play Console
2. Add your product IDs
3. Ensure your app is signed and uploaded to Play Console

Usage #

1. Basic Setup #

First, configure the dependency injection:

import 'package:flutter_gb_in_app_purchases/flutter_gb_in_app_purchases.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Configure dependency injection
  await configurePurchasesInjection(
    environment: AppEnvironment.production,
    purchasesConfig: InAppPurchasesConfig(
      // Optional: API endpoint to fetch product listings
      getProductsListingApiEndpoint: () => Uri.parse('https://your-api.com/products'),
      
      // Optional: Parse product listings response
      getProductsListingResponseParser: (response) {
        // Parse your API response and return PurchaseProductListing list
        return [];
      },
      
      // Optional: Transaction verification endpoint
      purchaseVerificationApiEndpoint: (transaction, params) {
        return Uri.parse('https://your-api.com/verify-purchase');
      },
      
      // Optional: Custom request mapper for verification
      purchaseVerificationRequestMapper: (request, transaction) {
        return request..body = {'transaction_id': transaction.id};
      },
      
      // Optional: Product type mapper
      productTypeMapper: (item, listings) {
        // Determine product type based on your business logic
        return ProductType.consumable;
      },
      
      // Complete purchases without verification (not recommended)
      completeWithoutVerifying: false,
    ),
  );
  
  runApp(MyApp());
}

2. Using the BLoC #

Wrap your app or specific widgets with the purchases BLoC:

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_gb_in_app_purchases/flutter_gb_in_app_purchases.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => PurchasesBloc(
        purchasesBlocConfig: PurchasesBlocConfig(
          autoInitialize: true,
          userReferenceMapper: () async => 'user_123', // Your user ID
          verificationParamBuilder: (transaction) {
            return {'user_id': 'user_123'};
          },
        ),
      ),
      child: MaterialApp(
        home: PurchaseScreen(),
      ),
    );
  }
}

3. Initialize and Get Products #

class PurchaseScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocBuilder<PurchasesBloc, PurchasesState>(
      builder: (context, state) {
        return Scaffold(
          appBar: AppBar(title: Text('In-App Purchases')),
          body: Column(
            children: [
              // Initialize purchases
              ElevatedButton(
                onPressed: () {
                  context.read<PurchasesBloc>().initialize();
                },
                child: Text('Initialize Purchases'),
              ),
              
              // Get store catalog
              ElevatedButton(
                onPressed: () {
                  context.read<PurchasesBloc>().add(
                    PurchasesEvent.getStoreCatalog(
                      productIds: {'premium_upgrade', 'coins_100'},
                    ),
                  );
                },
                child: Text('Load Products'),
              ),
              
              // Display products
              if (state.storeCatalog.data != null)
                Expanded(
                  child: ListView.builder(
                    itemCount: state.storeCatalog.data!.products.length,
                    itemBuilder: (context, index) {
                      final product = state.storeCatalog.data!.products[index];
                      return ListTile(
                        title: Text(product.title),
                        subtitle: Text(product.description),
                        trailing: Text(product.price),
                        onTap: () {
                          context.read<PurchasesBloc>().purchase(product);
                        },
                      );
                    },
                  ),
                ),
            ],
          ),
        );
      },
    );
  }
}

4. Handle Purchase States #

class PurchaseListener extends StatelessWidget {
  final Widget child;
  
  const PurchaseListener({Key? key, required this.child}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BlocListener<PurchasesBloc, PurchasesState>(
      listener: (context, state) {
        // Handle purchase completion
        if (state.isPurchasing.data == true) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Purchase completed!')),
          );
        }
        
        // Handle errors
        if (state.storeCatalog.data?.isLeft() == true) {
          final failure = state.storeCatalog.data?.fold(
            (failure) => failure,
            (success) => null,
          );
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Error: ${failure?.message}')),
          );
        }
      },
      child: child,
    );
  }
}

5. Restore Purchases #

// Restore purchases (typically called from a settings screen)
context.read<PurchasesBloc>().restorePurchases();

6. Subscription Changes (Android) #

// Change subscription (upgrade/downgrade)
context.read<PurchasesBloc>().changeSubscription(newProduct);

Configuration Options #

InAppPurchasesConfig #

PurchasesBlocConfig #

API Integration #

Product Listings API #

Your API should return product information in this format:

{
  "products": [
    {
      "product_id": "premium_upgrade",
      "title": "Premium Upgrade",
      "description": "Unlock premium features",
      "price": "4.99",
      "type": "non-consumable"
    }
  ]
}

Transaction Verification API #

Your verification endpoint will receive transaction details and should return verification results.

State Management #

The package provides comprehensive state management through BLoC:

• Initialization: Track initialization status
• Product Loading: Monitor catalog loading states
• Purchase States: Track individual purchase progress
• Transaction Updates: Real-time transaction monitoring
• Verification Status: Track server-side verification

Error Handling #

The package provides detailed error handling for common scenarios:

• Network failures
• Invalid products
• Purchase failures
• Verification failures
• Platform-specific errors

Testing #

The package is built with testing in mind. Use the mock configuration for testing:

final mockConfig = InAppPurchasesConfig.mock();

Dependencies #

This package depends on:

• flutter_gb_stack_base: Geekbears base utilities
• in_app_purchase: Core in-app purchase functionality
• flutter_bloc: State management
• dartz: Functional programming utilities
• built_value: Immutable data structures
• rxdart: Reactive extensions

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

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

Support #

For support, please open an issue in the GitLab repository or contact the Geekbears team.

Changelog #

See CHANGELOG.md for a list of changes and version history.