flare
## Description
Flare is a modern, lightweight Swift framework that simplifies working with in-app purchases and subscriptions. Built on top of StoreKit and StoreKit 2, it provides a clean, unified API with async/await support and includes ready-to-use UI components for seamless integration across all Apple platforms.
## โจ Features
- ๐๏ธ **Complete Purchase Support** - Consumable, non-consumable, and subscription purchases
- ๐ **Promotional Offers** - Support for promotional and introductory offers
- โก **Modern Swift** - Built with async/await for clean, readable code
- ๐ **StoreKit 1 & 2** - Unified API supporting both StoreKit versions
- ๐จ **UI Components** - Pre-built SwiftUI and UIKit views for product displays
- ๐ฑ **Cross-Platform** - iOS, tvOS, watchOS, macOS, and visionOS compatible
- ๐งช **Thoroughly Tested** - Complete unit, integration, and snapshot test coverage
## ๐ Table of Contents
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Fetching Products](#fetching-products)
- [Making Purchases](#making-purchases)
- [Managing Subscriptions](#managing-subscriptions)
- [Handling Transactions](#handling-transactions)
- [Promotional Offers](#promotional-offers)
- [FlareUI](#flareui)
- [SwiftUI Integration](#swiftui-integration)
- [UIKit Integration](#uikit-integration)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
## ๐ฑ Requirements
| Package | Supported Platforms | Xcode | Minimum Swift Version |
|---------|-------------------|-------|----------------------|
| **Flare** | iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 7.0+ / visionOS 1.0+ | 15.4+ | 5.10 |
| **FlareUI** | iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ | 15.4+ | 5.10 |
## ๐ Installation
### Swift Package Manager
Add the following dependency to your `Package.swift`:
```swift
dependencies: [
.package(url: "https://github.com/space-code/flare.git", from: "3.3.1")
]
```
**Or via Xcode:**
1. File > Add Package Dependencies
2. Enter package URL: `https://github.com/space-code/flare.git`
3. Select version requirements
The package contains two libraries:
- **Flare** - Core in-app purchase functionality
- **FlareUI** - Ready-to-use UI components for SwiftUI and UIKit
## Quick Start
```swift
import Flare
// Configure Flare
Flare.configure(with: .init(applicationUsername: "UUID"))
// Fetch products
let products = try await Flare.shared.fetch(productIDs: ["premium_monthly"])
// Purchase a product
let transaction = try await Flare.shared.purchase(product: products.first!)
// Finish the transaction
Flare.shared.finish(transaction: transaction, completion: nil)
```
## Usage
### Fetching Products
Retrieve product information from the App Store:
```swift
import Flare
// Fetch single product
let productIDs = ["com.app.premium"]
let products = try await Flare.shared.fetch(productIDs: productIDs)
// Fetch multiple products
let subscriptionIDs = [
"com.app.monthly",
"com.app.yearly",
"com.app.lifetime"
]
let subscriptions = try await Flare.shared.fetch(productIDs: subscriptionIDs)
// Access product details
for product in products {
print("Product: \(product.localizedTitle)")
print("Price: \(product.localizedPriceString)")
print("Description: \(product.localizedDescription)")
}
```
### Making Purchases
Handle purchases with simple async/await syntax:
```swift
import Flare
func purchasePremium() async throws {
let productID = "com.app.premium"
let products = try await Flare.shared.fetch(productIDs: [productID])
guard let product = products.first else {
throw IAPError.storeProductNotAvailable
}
do {
let transaction = try await Flare.shared.purchase(product: product)
await unlockPremiumFeatures()
Flare.shared.finish(transaction: transaction, completion: nil)
} catch {
guard let error = error as? IAPError else { return }
switch error {
case .paymentCancelled:
print("โ User cancelled the purchase")
default:
print("โ Purchase failed: \(error)")
}
}
}
```
### Managing Subscriptions
Work with subscription products and their states:
```swift
import Flare
func purchaseSubscription(product: StoreProduct) async throws {
do {
let transaction = try await Flare.shared.purchase(product: product)
Flare.shared.finish(transaction: transaction, completion: nil)
} catch {
guard let error = error as? IAPError else { return }
// Handle the error
}
}
```
### Handling Transactions
Manage transaction lifecycle:
```swift
import Flare
// Finish a transaction after delivering content
func completeTransaction(_ transaction: StoreTransaction) {
Flare.shared.finish(transaction: transaction) {
print("โ
Transaction completed successfully")
}
}
// Restore previous purchases
func restorePurchases() async throws {
do {
try await Flare.shared.restore()
print("โ
Purchases restored successfully")
} catch {
print("โ Failed to restore purchases: \(error)")
}
}
// Listen for transaction updates
func observeTransactions() {
Flare.shared.addTransactionObserver { result in
switch result {
case let .success(transaction):
handleTransaction(transaction)
case let .failure(error):
print("Transaction error: \(error)")
}
}
}
```
### Promotional Offers
Support promotional and introductory offers:
```swift
import Flare
func purchaseWithOffer(product: StoreProduct, offer: PromotionalOffer) async throws {
do {
let transaction = try await Flare.shared.purchase(
product: product,
promotionalOffer: offer
)
print("โ
Purchased with promotional offer!")
Flare.shared.finish(transaction: transaction, completion: nil)
} catch {
guard let error = error as? IAPError else { return }
// Handle the error
}
}
```
## ๐จ FlareUI
FlareUI provides ready-to-use UI components for displaying products and handling purchases in both SwiftUI and UIKit.
### SwiftUI Integration
Display products with built-in SwiftUI views:
```swift
import SwiftUI
import FlareUI
struct StoreView: View {
var body: some View {
NavigationView {
SubscriptionsView(ids: ["com.product.subscription"])
.navigationTitle("Premium Features")
}
}
}
```
### UIKit Integration
Integrate with UIKit applications:
```swift
import UIKit
import FlareUI
let subscriptionsVC = SubscriptionsViewController(ids: [com.company.subscription_id])
let nav = UINavigationController(rootViewController: subscriptionsVC)
present(nav, animated: true)
```
## Documentation
Comprehensive documentation is available:
- **[Flare Documentation](https://space-code.github.io/flare/flare/documentation/flare/)** - Core framework integration and APIs
- **[FlareUI Documentation](https://space-code.github.io/flare/flareui/documentation/flareui/)** - UI components, customization, and integration guides
## Contributing
We love contributions! Please read our [Contributing Guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.
### Development Setup
Bootstrap the development environment:
```bash
mise install
```
### Code of Conduct
This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
## Author
**Nikita Vasilev**
- Email: [nv3212@gmail.com](mailto:nv3212@gmail.com)
- GitHub: [@ns-vasilev](https://github.com/ns-vasilev)
## License
Flare is released under the MIT license. See [LICENSE](LICENSE) for details.
---
**[โฌ back to top](#description)**
Made with โค๏ธ by [space-code](https://github.com/space-code)