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 #

Enable Wallet capability in your iOS project:
- Open ios/Runner.xcworkspace in Xcode
- Select your target → Signing & Capabilities
- Add "Wallet" capability
Configure your Apple Developer account:
- Create a Pass Type ID in Apple Developer Console
- Generate certificates for pass signing

Android Setup #

Add Google Wallet API to your project:
- Enable Google Wallet API in Google Cloud Console
- Configure OAuth 2.0 credentials
Ensure your app uses play-services-pay (automatically included by the plugin):
```
implementation 'com.google.android.gms:play-services-pay:16.5.0'
```

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 #

New unified API: Replace platform-specific calls with unified methods
Updated models: Use new WalletCard model instead of separate iOS/Android models
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 #

Fork the repository
Clone your fork: git clone https://github.com/your-username/flutter_wallet_card.git
Install dependencies: flutter pub get
Run tests: flutter test
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
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Changelog #

See CHANGELOG.md for a detailed list of changes.

Made with ❤️ for the Flutter community

flutter_wallet_card 5.0.0 flutter_wallet_card: ^5.0.0 copied to clipboard

Metadata