flutter_wallet_card

Flutter Wallet Card

A comprehensive Flutter plugin for creating and managing wallet cards on both iOS (Apple Wallet) and Android (Google Wallet). This plugin provides a unified API for generating, adding, and managing wallet passes across platforms.

Features

Cross-Platform Support

• iOS: Full Apple Wallet (Passkit) integration
• Android: Google Wallet integration
• Unified API: Single codebase for both platforms

Card Operations

• ✅ Check wallet availability
• ✅ Add cards to wallet
• ✅ Check if card is already added
• ✅ View cards in wallet
• ✅ Generate card files from data
• ✅ Parse existing card files
• ✅ Download cards from URLs

Card Types Supported

• Generic Cards: General purpose cards
• Boarding Passes: Flight tickets
• Coupons: Discount and promotional cards
• Event Tickets: Concert, sports, and event passes
• Store Cards: Loyalty and membership cards

Advanced Features

• 🎨 Custom colors and styling
• 📍 Location-based relevance
• 📅 Date-based relevance
• 🔒 Secure certificate signing (iOS)
• 🌐 Network download support
• 🧪 Comprehensive test coverage

Installation

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

dependencies:
  flutter_wallet_card: ^5.0.0

Then run:

flutter pub get

Platform Setup

iOS Setup

1. Enable Wallet capability in your iOS project:

   • Open ios/Runner.xcworkspace in Xcode
   • Select your target → Signing & Capabilities
   • Add "Wallet" capability

2. Configure your Apple Developer account:

   • Create a Pass Type ID in Apple Developer Console
   • Generate certificates for pass signing

Android Setup

1. Add Google Wallet API to your project:

   • Enable Google Wallet API in Google Cloud Console
   • Configure OAuth 2.0 credentials

2. Ensure your app uses play-services-pay (automatically included by the plugin):

   implementation 'com.google.android.gms:play-services-pay:16.5.0'
   

3. Update Android manifest (automatically handled by plugin):

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   

Usage

Basic Example

import 'package:flutter/material.dart';
import 'package:flutter_wallet_card/flutter_wallet_card.dart';
import 'package:flutter_wallet_card/models/wallet_card.dart';

// Check if wallet is available
bool isAvailable = await FlutterWalletCard.isWalletAvailable;

if (isAvailable) {
  // Create a wallet card
  final card = WalletCard(
    id: 'my-card-123',
    type: WalletCardType.generic,
    platformData: {
      // iOS specific data
      'passTypeIdentifier': 'pass.com.yourcompany.yourpass',
      'teamIdentifier': 'YOUR_TEAM_ID',
      // Android specific data
      'issuerId': 'your-issuer-id',
      'classId': 'your-class-id',
    },
    metadata: WalletCardMetadata(
      title: 'My Awesome Card',
      description: 'This is a sample wallet card',
      organizationName: 'Your Company',
      serialNumber: 'CARD123',
    ),
    visuals: WalletCardVisuals(
      backgroundColor: Color(0xFF1E88E5),
      foregroundColor: Color(0xFFFFFFFF),
      labelColor: Color(0xFFE3F2FD),
    ),
  );

  // Add card to wallet
  bool success = await FlutterWalletCard.addToWallet(card);

  if (success) {
    print('Card added successfully!');
  }
}

Advanced Usage

Creating Cards with Locations

final cardWithLocation = WalletCard(
  id: 'location-card',
  type: WalletCardType.storeCard,
  platformData: {
    'passTypeIdentifier': 'pass.com.yourcompany.store',
    'teamIdentifier': 'YOUR_TEAM_ID',
  },
  metadata: WalletCardMetadata(
    title: 'Store Loyalty Card',
    description: 'Get rewards at our store',
    organizationName: 'Your Store',
    serialNumber: 'STORE001',
    locations: [
      WalletCardLocation(
        latitude: 37.7749,
        longitude: -122.4194,
        altitude: 100.0,
        relevantText: 'Welcome to our San Francisco store!',
      ),
    ],
  ),
  visuals: WalletCardVisuals(
    backgroundColor: Color(0xFF4CAF50),
    foregroundColor: Color(0xFFFFFFFF),
  ),
);

Generating Card Files

// Generate a card file for sharing or storage
File cardFile = await FlutterWalletCard.generateCardFile(card);

print('Card file created at: ${cardFile.path}');

Adding Cards from URLs

// Download and add a card from a URL
try {
  bool success = await FlutterWalletCard.addFromUrl(
    'https://example.com/mycard.pkpass',
  );

  print('Card added: $success');
} catch (e) {
  print('Failed to add card from URL: $e');
}

Parsing Existing Card Files

// Parse a wallet card from a local file
WalletCard card = await FlutterWalletCard.parseFromFile(File('/path/to/card.pkpass'));
print('Card title: ${card.metadata.title}');

Platform-Specific Features

// iOS: Add multiple cards at once
if (Platform.isIOS) {
  List<WalletCard> cards = [card1, card2, card3];
  bool success = await FlutterWalletCard.addMultipleToWallet(cards);
}

// Android: Save pass with JWT
if (Platform.isAndroid) {
  String jwt = 'your-google-wallet-jwt';
  bool success = await FlutterWalletCard.savePassWithJwt(jwt);
  
  // Create a pass link
  String link = await FlutterWalletCard.createPassLink({
    'objectId': 'your-object-id',
  });
}

API Reference

Core Methods

Method	Description	Returns
isWalletAvailable	Check if wallet is available on device (getter)	Future<bool>
platformType	Get the current platform type (getter)	WalletPlatformType
isCardAdded(String identifier)	Check if specific card is added	Future<bool>
addToWallet(WalletCard card)	Add card to wallet	Future<bool>
addFromFile(File file, {Map? metadata})	Add card from existing file	Future<bool>
addFromUrl(String url, {Map? metadata})	Download and add card from URL	Future<bool>
viewInWallet(String identifier)	Open card in wallet app	Future<bool>
generateCardFile(WalletCard card)	Generate card file	Future<File>
parseFromFile(File file)	Parse card from file	Future<WalletCard>
cleanup({Duration? olderThan})	Clean up temporary files	Future<void>

iOS-Specific Methods

Method	Description	Returns
addMultipleToWallet(List<WalletCard> cards)	Add multiple cards	Future<bool>
validatePass(File file)	Validate a pass file	Future<Map<String, dynamic>>
getPassInfo(String identifier)	Get detailed pass info	Future<Map<String, dynamic>>
isValidPass(File file)	Check if a pass file is valid	Future<bool>

Android-Specific Methods

Method	Description	Returns
savePassWithJwt(String jwt)	Save pass using JWT	Future<bool>
createPassLink(Map<String, dynamic> data)	Create pass link	Future<String>

Models

WalletCard

The main model representing a wallet card:

class WalletCard {
  final String id;
  final WalletCardType type;
  final Map<String, dynamic> platformData;
  final WalletCardMetadata metadata;
  final WalletCardVisuals? visuals;
  final File? file;
}

WalletCardMetadata

Card information and content:

class WalletCardMetadata {
  final String title;
  final String? subtitle;
  final String? description;
  final String organizationName;
  final String serialNumber;
  final DateTime? expirationDate;
  final DateTime? relevantDate;
  final List<WalletCardLocation>? locations;
  final Map<String, String>? customFields;
}

WalletCardVisuals

Card appearance and styling. Colors are stored as Color objects and serialized as hex strings (e.g. #FF0000) in JSON:

class WalletCardVisuals {
  final Color? backgroundColor;
  final Color? foregroundColor;
  final Color? labelColor;
  final String? logoText;
  final Map<String, String>? images;
}

Error Handling

The plugin throws WalletException for wallet-related errors:

try {
  await FlutterWalletCard.addToWallet(card);
} on WalletException catch (e) {
  print('Wallet error: ${e.message}');
  if (e.originalError != null) {
    print('Original error: ${e.originalError}');
  }
} catch (e) {
  print('General error: $e');
}

Testing

Run the test suite:

flutter test

For comprehensive testing:

flutter test test/test_all.dart

Migration from v3.x

If you're upgrading from version 3.x, here are the key changes:

Breaking Changes

1. New unified API: Replace platform-specific calls with unified methods
2. Updated models: Use new WalletCard model instead of separate iOS/Android models
3. Method names: Some method names have changed for consistency

Migration Example

Old (v3.x):

// iOS
await FlutterWalletCard.addPasskit(passData);

// Android
await FlutterWalletCard.addGoogleWallet(walletData);

New (v4.x):

// Unified
final card = WalletCard(/* ... */);
await FlutterWalletCard.addToWallet(card);

Development Resources

• GitHub Actions Workflows - CI/CD and automation
• Publishing Scripts - Package publishing tools

🚀 Development & Deployment

Local Development

# Validate package before publishing
./scripts/publish-package.sh validate

# Run comprehensive tests
./scripts/publish-package.sh test

Publishing

# Create a new release
./scripts/publish-package.sh release --version 1.0.0

# Publish to pub.dev (manual)
./scripts/publish-package.sh publish

Automated Workflows

This project includes comprehensive GitHub Actions workflows:

• CI/CD Pipeline - Automated testing, validation, and quality checks

• Package Publishing - Automated pub.dev releases

• Release Management - Version bumping and changelog generation

See GitHub Actions Documentation for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/flutter_wallet_card.git
3. Install dependencies: flutter pub get
4. Run tests: flutter test
5. Start documentation server: ./scripts/deploy-docs.sh dev

Before Submitting

• Run ./scripts/publish-package.sh validate to ensure quality
• Update documentation if needed
• Add tests for new features
• Follow existing code style

License

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

Support

• 📧 Email: [michal.makowski97@gmail.com](mailto:michal.makowski97@gmail.com)
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for a detailed list of changes.

---

Made with ❤️ for the Flutter community