WebEferen/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

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](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

Michał Makowski ↗

तकनीकी विषय

इस रिपॉज़िटरी के पैकेज

flutter_wallet_card

उपयोग की गई निर्भरताएँ

मूल README