logikonline
66c8ec8ecf
Implement BmcSupporterService to verify supporters via BMC API with configurable caching. Add SupporterEmail and HideIfSupporter properties to all controls to automatically hide donation prompts for existing supporters. Replace PNG logo with SVG for crisp rendering at all scales. Add BmcOptions and BmcConfiguration for library-wide settings. Bump version to 1.1.0.
406 lines
12 KiB
Markdown
406 lines
12 KiB
Markdown
# BuyMeCoffee.Maui
|
|
|
|
[](https://dotnet.microsoft.com/apps/maui)
|
|
[](https://dotnet.microsoft.com/apps/maui)
|
|
[](LICENSE)
|
|
[](https://git.marketally.com/misc/bmc.maui/packages)
|
|
|
|
A comprehensive .NET MAUI library for integrating Buy Me a Coffee support into your cross-platform applications. Provides branded buttons, QR codes, and interactive widgets with official BMC styling and theming.
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Quick Start](#quick-start)
|
|
- [Controls](#controls)
|
|
- [BuyMeACoffeeButton](#buymeacoffeebutton)
|
|
- [BuyMeACoffeeQrCode](#buymeacoffeeqrcode)
|
|
- [BuyMeACoffeeWidget](#buymeacoffeewidget)
|
|
- [Supporter Verification](#supporter-verification)
|
|
- [Theming](#theming)
|
|
- [API Reference](#api-reference)
|
|
- [Platform Support](#platform-support)
|
|
- [Dependencies](#dependencies)
|
|
- [Examples](#examples)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
## Features
|
|
|
|
- **BuyMeACoffeeButton** - Branded button with official coffee cup logo and 8 color themes
|
|
- **BuyMeACoffeeQrCode** - QR code generator with embedded BMC logo overlay
|
|
- **BuyMeACoffeeWidget** - Full-featured support widget with amount selection, name/message fields, and monthly toggle
|
|
- **Official Branding** - Crisp SVG-based logos via MAUI asset pipeline, authentic Buy Me a Coffee colors and styling
|
|
- **Supporter Verification** - Auto-hide controls for users who have already supported you via the BMC API
|
|
- **Cross-Platform** - Supports Android, iOS, macOS, and Windows
|
|
- **Customizable** - Extensive theming and styling options
|
|
- **Touch Optimized** - Smooth animations and hover effects
|
|
- **QR Code Generation** - High-quality QR codes with error correction level H
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- .NET 10.0 SDK or later
|
|
- .NET MAUI workload installed
|
|
|
|
### NuGet Package
|
|
|
|
Add the MarketAlly NuGet source to your `NuGet.config`:
|
|
|
|
```xml
|
|
<configuration>
|
|
<packageSources>
|
|
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
|
|
<add key="MarketAlly" value="https://git.marketally.com/api/packages/misc/nuget/index.json" />
|
|
</packageSources>
|
|
</configuration>
|
|
```
|
|
|
|
Then add the package reference:
|
|
|
|
```xml
|
|
<PackageReference Include="BuyMeCofee.Maui" Version="1.1.0" />
|
|
```
|
|
|
|
Or via CLI:
|
|
|
|
```bash
|
|
dotnet add package BuyMeCofee.Maui --version 1.1.0
|
|
```
|
|
|
|
### Register in MauiProgram.cs
|
|
|
|
```csharp
|
|
using BuyMeCofee.Maui;
|
|
|
|
public static class MauiProgram
|
|
{
|
|
public static MauiApp CreateMauiApp()
|
|
{
|
|
var builder = MauiApp.CreateBuilder();
|
|
builder
|
|
.UseMauiApp<App>()
|
|
.UseBuyMeACoffee(); // Add this line
|
|
|
|
return builder.Build();
|
|
}
|
|
}
|
|
```
|
|
|
|
This automatically registers SkiaSharp dependencies required for QR code rendering.
|
|
|
|
## Quick Start
|
|
|
|
Add the namespace to your XAML page:
|
|
|
|
```xml
|
|
xmlns:bmc="clr-namespace:BuyMeCofee.Maui.Controls;assembly=BuyMeCofee.Maui"
|
|
```
|
|
|
|
Add a button to your page:
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeButton
|
|
Username="yourname"
|
|
ButtonText="Buy me a coffee"
|
|
Theme="Yellow" />
|
|
```
|
|
|
|
## Controls
|
|
|
|
### BuyMeACoffeeButton
|
|
|
|
A branded button that opens your Buy Me a Coffee page in the default browser.
|
|
|
|
#### Basic Usage
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeButton
|
|
Username="yourname"
|
|
Theme="Yellow" />
|
|
```
|
|
|
|
#### With Custom Styling
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeButton
|
|
Username="yourname"
|
|
ButtonText="Support My Work"
|
|
Theme="Violet"
|
|
CornerRadius="12"
|
|
FontSize="18"
|
|
CupSize="32"
|
|
HorizontalOptions="Center" />
|
|
```
|
|
|
|
#### Custom Theme
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeButton
|
|
Username="yourname"
|
|
Theme="Custom"
|
|
CustomBackgroundColor="#FF6B6B"
|
|
CustomTextColor="White"
|
|
ButtonText="Donate" />
|
|
```
|
|
|
|
#### Properties
|
|
|
|
| Property | Type | Default | Description |
|
|
|----------|------|---------|-------------|
|
|
| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
|
|
| `ButtonText` | `string` | `"Buy me a coffee"` | Button label text |
|
|
| `Theme` | `BmcButtonTheme` | `Yellow` | Color theme preset |
|
|
| `CustomBackgroundColor` | `Color?` | `null` | Background color (Custom theme only) |
|
|
| `CustomTextColor` | `Color?` | `null` | Text color (Custom theme only) |
|
|
| `CornerRadius` | `double` | `8.0` | Border corner radius |
|
|
| `FontSize` | `double` | `16.0` | Button text font size |
|
|
| `CupSize` | `double` | `28.0` | Coffee cup logo height |
|
|
| `SupporterEmail` | `string?` | `null` | Email to check against supporters list |
|
|
| `HideIfSupporter` | `bool` | `false` | Auto-hide if email is a verified supporter |
|
|
|
|
### BuyMeACoffeeQrCode
|
|
|
|
Generates a QR code linking to your BMC profile with the coffee cup logo overlaid in the center.
|
|
|
|
#### Basic Usage
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeQrCode
|
|
Username="yourname"
|
|
Size="250" />
|
|
```
|
|
|
|
#### With Custom Colors
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeQrCode
|
|
Username="yourname"
|
|
Size="300"
|
|
ForegroundColor="DarkBlue"
|
|
BackgroundColor="LightYellow"
|
|
LogoSizeFraction="0.3" />
|
|
```
|
|
|
|
#### Properties
|
|
|
|
| Property | Type | Default | Description |
|
|
|----------|------|---------|-------------|
|
|
| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
|
|
| `Size` | `double` | `200.0` | Width and height of the QR code |
|
|
| `ForegroundColor` | `Color` | `Black` | QR code module color |
|
|
| `BackgroundColor` | `Color` | `White` | QR code background color |
|
|
| `LogoSizeFraction` | `double` | `0.25` | Logo size as fraction of QR code (0.0-0.35) |
|
|
| `SupporterEmail` | `string?` | `null` | Email to check against supporters list |
|
|
| `HideIfSupporter` | `bool` | `false` | Auto-hide if email is a verified supporter |
|
|
|
|
### BuyMeACoffeeWidget
|
|
|
|
A full-featured support widget with amount entry, preset chips, name/message fields, and monthly subscription toggle.
|
|
|
|
#### Basic Usage
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeWidget
|
|
Username="yourname"
|
|
DisplayName="John Doe" />
|
|
```
|
|
|
|
#### With Custom Configuration
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeWidget
|
|
Username="yourname"
|
|
DisplayName="John Doe"
|
|
DefaultAmount="10"
|
|
SuggestedAmounts="10,25,50,100"
|
|
AccentColor="#6C5CE7"
|
|
ShowMonthlyOption="True"
|
|
SupportButtonText="Send Support"
|
|
HorizontalOptions="Center" />
|
|
```
|
|
|
|
#### Handling Support Events
|
|
|
|
```csharp
|
|
private void OnSupportRequested(object sender, SupportRequestedEventArgs e)
|
|
{
|
|
Console.WriteLine($"Support requested by: {e.Name ?? "Anonymous"}");
|
|
Console.WriteLine($"Amount: ${e.Amount}");
|
|
Console.WriteLine($"Message: {e.Message ?? "No message"}");
|
|
Console.WriteLine($"Monthly: {e.IsMonthly}");
|
|
}
|
|
```
|
|
|
|
#### Properties
|
|
|
|
| Property | Type | Default | Description |
|
|
|----------|------|---------|-------------|
|
|
| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
|
|
| `DisplayName` | `string` | `""` | Name displayed in header ("Support {DisplayName}") |
|
|
| `SuggestedAmounts` | `int[]` | `[25, 50, 100]` | Preset amount chips |
|
|
| `DefaultAmount` | `int` | `5` | Initial amount in entry field |
|
|
| `AccentColor` | `Color` | `#6C5CE7` | Support button background color |
|
|
| `ShowMonthlyOption` | `bool` | `true` | Show "Make this monthly" checkbox |
|
|
| `SupportButtonText` | `string` | `"Support"` | Support button label text |
|
|
| `SupporterEmail` | `string?` | `null` | Email to check against supporters list |
|
|
| `HideIfSupporter` | `bool` | `false` | Auto-hide if email is a verified supporter |
|
|
|
|
#### Events
|
|
|
|
| Event | EventArgs | Description |
|
|
|-------|-----------|-------------|
|
|
| `SupportRequested` | `SupportRequestedEventArgs` | Raised when user taps Support button, before opening browser |
|
|
|
|
**SupportRequestedEventArgs Properties:**
|
|
|
|
```csharp
|
|
public class SupportRequestedEventArgs : EventArgs
|
|
{
|
|
public string Username { get; init; }
|
|
public int Amount { get; init; }
|
|
public string? Name { get; init; }
|
|
public string? Message { get; init; }
|
|
public bool IsMonthly { get; init; }
|
|
}
|
|
```
|
|
|
|
## Supporter Verification
|
|
|
|
The library can automatically check if a user has already supported you via the Buy Me a Coffee API. When verified, controls can auto-hide themselves — useful for removing donation prompts for existing supporters.
|
|
|
|
### Setup
|
|
|
|
Get your API access token from [Buy Me a Coffee Developer Dashboard](https://developers.buymeacoffee.com/).
|
|
|
|
Configure the token in `MauiProgram.cs`:
|
|
|
|
```csharp
|
|
builder.UseBuyMeACoffee(options =>
|
|
{
|
|
options.AccessToken = "your_bmc_api_token";
|
|
options.CacheDuration = TimeSpan.FromHours(1); // default
|
|
});
|
|
```
|
|
|
|
### Usage
|
|
|
|
Add `SupporterEmail` and `HideIfSupporter` to any control:
|
|
|
|
```xml
|
|
<bmc:BuyMeACoffeeButton
|
|
Username="yourname"
|
|
Theme="Yellow"
|
|
SupporterEmail="{Binding CurrentUserEmail}"
|
|
HideIfSupporter="True" />
|
|
```
|
|
|
|
When `HideIfSupporter` is `true` and the email matches a one-time supporter or active member, the control sets `IsVisible = false`.
|
|
|
|
The service queries both `/api/v1/supporters` (one-time) and `/api/v1/subscriptions` (members) endpoints, caches results in memory, and fails silently if the API is unreachable.
|
|
|
|
## Theming
|
|
|
|
### Button Themes
|
|
|
|
The library includes 8 official Buy Me a Coffee color themes plus a custom option:
|
|
|
|
```csharp
|
|
public enum BmcButtonTheme
|
|
{
|
|
Yellow, // #FFDD00 - Official BMC brand color
|
|
Black, // #0D0C22 - Dark theme
|
|
White, // #FFFFFF - Light theme with stroke
|
|
Blue, // #5F7FFF
|
|
Violet, // #BD5CFF
|
|
Orange, // #FF813F
|
|
Red, // #FF6073
|
|
Green, // #78DEC7
|
|
Custom // Use CustomBackgroundColor and CustomTextColor
|
|
}
|
|
```
|
|
|
|
### Brand Colors Reference
|
|
|
|
```csharp
|
|
public static class BmcColors
|
|
{
|
|
public const string CupYellow = "#FFDD00";
|
|
public const string BrandDark = "#0D0C22";
|
|
public const string WidgetPurple = "#6C5CE7";
|
|
public const string WhiteStroke = "#E0E0E0";
|
|
}
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Extension Methods
|
|
|
|
```csharp
|
|
// Basic registration (no API features)
|
|
public static MauiAppBuilder UseBuyMeACoffee(this MauiAppBuilder builder);
|
|
|
|
// With API configuration (enables supporter verification)
|
|
public static MauiAppBuilder UseBuyMeACoffee(this MauiAppBuilder builder, Action<BmcOptions> configure);
|
|
```
|
|
|
|
### BmcOptions
|
|
|
|
```csharp
|
|
public class BmcOptions
|
|
{
|
|
public string? AccessToken { get; set; }
|
|
public TimeSpan CacheDuration { get; set; } = TimeSpan.FromHours(1);
|
|
}
|
|
```
|
|
|
|
### Constants
|
|
|
|
```csharp
|
|
public static class BmcConstants
|
|
{
|
|
public const string BaseUrl = "https://buymeacoffee.com/";
|
|
public const string DefaultButtonText = "Buy me a coffee";
|
|
public const string DefaultSupportButtonText = "Support";
|
|
public const double ButtonCornerRadius = 8.0;
|
|
public const double WidgetCornerRadius = 16.0;
|
|
public static readonly int[] DefaultSuggestedAmounts = [25, 50, 100];
|
|
}
|
|
```
|
|
|
|
## Platform Support
|
|
|
|
| Platform | Minimum Version | Status |
|
|
|----------|----------------|--------|
|
|
| **Android** | API 21 (Android 5.0) | Supported |
|
|
| **iOS** | 15.0+ | Supported |
|
|
| **macOS** (Catalyst) | 15.0+ | Supported |
|
|
| **Windows** | 10.0.17763.0+ | Supported |
|
|
|
|
## Dependencies
|
|
|
|
```xml
|
|
<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
|
|
<PackageReference Include="QRCoder" Version="1.6.0" />
|
|
<PackageReference Include="SkiaSharp.Views.Maui.Controls" Version="3.116.1" />
|
|
```
|
|
|
|
## Support This Project
|
|
|
|
If this library saved you time, consider buying me a coffee:
|
|
|
|
[](https://buymeacoffee.com/logikonline)
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. See the LICENSE file for details.
|
|
|
|
---
|
|
|
|
**Not affiliated with Buy Me a Coffee.** This is an unofficial community library. Buy Me a Coffee and its branding are trademarks of Buy Me a Coffee LLC.
|