PassKitHelper 3.3.0
dotnet add package PassKitHelper --version 3.3.0
NuGet\Install-Package PassKitHelper -Version 3.3.0
<PackageReference Include="PassKitHelper" Version="3.3.0" />
paket add PassKitHelper --version 3.3.0
#r "nuget: PassKitHelper, 3.3.0"
// Install PassKitHelper as a Cake Addin #addin nuget:?package=PassKitHelper&version=3.3.0 // Install PassKitHelper as a Cake Tool #tool nuget:?package=PassKitHelper&version=3.3.0
PassKit Helper
Helper library for all your Apple PassKit (Apple Wallet, Apple Passbook) needs: create passes, sign pass packages, receive [de]install notifications and send pass updates.
Attention: Apple Developer Account required!
Features
- Create pass packages (
*.pkpass
files):- With Fluent-styled
PassInfoBuilder
andPassPackageBuilder
- Using
byte[]
and/orStream
as content images - Using
byte[]
orStream
orX509Certificate2
as certificates - Receive
MemoryStream
as result (save it to file or write to HttpResponse)
- With Fluent-styled
- Receive notifications from Apple about pass [de]installations and send updates:
- Add
UsePassKitMiddleware
into yourStartup.Configure()
- Implement
IPassKitService
for real processing.
- Add
Samples
1. Configure to create passes
For console app
var options = new PassKitOptions()
{
PassCertificate = new X509Certificate2(File.ReadAllBytes("pass.pfx")),
AppleCertificate = new X509Certificate2(File.ReadAllBytes("AppleWWDRCA.cer")),
ConfigureNewPass =
p => p.Standard
.PassTypeIdentifier("your-pass-type-identifier")
.TeamIdentifier("your-team-identifier")
// Add more "defaults" here if needed
};
IPassKitHelper passKitHelper = new PassKitHelper(options);
For web app
public void ConfigureServices(IServiceCollection services)
{
services.AddPassKitHelper(options =>
{
options.PassCertificate = new X509Certificate2(File.ReadAllBytes("pass.pfx"));
options.AppleCertificate = new X509Certificate2(File.ReadAllBytes("AppleWWDRCA.cer"));
options.ConfigureNewPass =
p => p.Standard
.PassTypeIdentifier("your-pass-type-identifier")
.TeamIdentifier("your-team-identifier")
// Add more "defaults" here if needed
});
}
2. Creat pass and pass package file
Check Apple's PassKit Package Format Reference for detailed description of all fields and valid values.
var pass = passKitHelper.CreateNewPass()
// Ths pass already have `PassTypeIdentifier`, `TeamIdentifier`
// and all other values you configured in options.
.Standard
.SerialNumber("PassKitHelper")
.OrganizationName("PassKit")
.Description("PassKitHelper demo pass")
.VisualAppearance
.Barcodes("1234567890128", BarcodeFormat.Code128)
.LogoText("PassKit Helper demo pass")
.ForegroundColor("rgb(44, 62, 80)")
.BackgroundColor("rgb(149, 165, 166)")
.LabelColor("rgb(236, 240, 241)")
.StoreCard
.PrimaryFields
.Add("version")
.Label("Library version")
.Value(libraryVersion)
.AuxiliaryFields
.Add("github")
.Label("GitHub link")
.Value("https://github.com/justdmitry/PassKitHelper");
var passPackage = passKitHelper.CreateNewPassPackage(pass)
.Icon(await File.ReadAllBytesAsync("images/icon.png"))
.Icon2X(await File.ReadAllBytesAsync("images/icon@2x.png"))
.Icon3X(await File.ReadAllBytesAsync("images/icon@3x.png"))
.Logo(await File.ReadAllBytesAsync("images/logo.jpg"))
.Strip(await File.ReadAllBytesAsync("images/strip.jpg"))
.Strip2X(await File.ReadAllBytesAsync("images/strip@2x.jpg"))
.Strip3X(await File.ReadAllBytesAsync("images/strip@3x.jpg"));
MemoryStream packageFile = await passPackage.SignAndBuildAsync();
// Now you have to "deliver" package file to user using any channel you have
// (save as attachment in email, download from your webapp etc)
await File.WriteAllBytesAsync("Sample.pkpass", packageFile.ToArray());
Code above will create this beautiful pass:
3. Implementing WebService for interaction
Apple's server can call your endpoint/server to notify about user installed/deinstalled your pass, to fetch updated version of pass (when user 'pulls down' pass in Wallet). You will be able to send pushes when you want to update pass in user's wallet. Check Apple's PassKit Web Service Reference for technical details.
3.1. Implement IPassKitService
public class PassKitService : IPassKitService
{
public Task<int> RegisterDeviceAsync(…) {…}
public Task<int> UnregisterDeviceAsync(…) {…}
public Task<(int status, string[]? passes, string? tag)> GetAssociatedPassesAsync(…) {…}
public Task<(int statusCode, MemoryStream? passData)> GetPassAsync(…) {…}
public Task ProcessLogsAsync(…) {…}
}
3.2. Register in Startup
public void ConfigureServices(IServiceCollection services)
{
...
services.AddSingleton<IPassService, PassService>();
}
public void Configure(IApplicationBuilder app)
{
...
app.UsePassKitMiddleware("/callbacks/passkit");
...
}
3.3 Add information inside your passes
You need publicly-accessible url/hostname for your server, and it must be secured with https/ssl.
Add this information into your passes:
var pass = passKitHelper.CreateNewPass()
// your
// original
// pass content
// goes here
.WebService
.AuthenticationToken("some-random-secret-string")
.WebServiceURL("https://you.server.com/callbacks/passkit")
AuthenticationToken is some "secret" string that you use to differentiate legal pass owners and malicious hackers.
WebServiceURL is hostname of your server and path that equal to one in UsePassKitMiddleware
in previous step.
3.4. Send push updates
When users install your pass packge to their iOS and Mac devices - Apple server call your RegisterDeviceAsync
. Save pushToken
value in database, and when you need to update pass on user device - call IPassKitHelper.SendPushNotificationAsync(pushToken)
.
Installation
Use NuGet package PassKitHelper
Dependencies
For netcoreapp3.1
:
- Microsoft.Extensions.Http, v3.1.1
- Newtonsoft.Json, v12.0.2
- System.Security.Cryptography.Pkcs, v4.6.0
For netstandard2.0
:
- Microsoft.AspNetCore.Http.Abstractions, v2.1.1
- Microsoft.Extensions.DependencyInjection.Abstractions, v2.1.1
- Microsoft.Extensions.Logging.Abstractions, v2.1.1
- Microsoft.Extensions.Http, v2.1.1
- Newtonsoft.Json, v12.0.2
- System.Security.Cryptography.Pkcs, v4.6.0
Dvelopment & Testing
You need netcore3.1
to run build and tests;
Tests can be run with dotnet test
.
Credits
- Thanks for inspiration to Tomas McGuinness and his dotnet-passbook package.
- Thanks to maxpixel.net for sample kitten images.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.AspNetCore.Http.Abstractions (>= 2.1.1)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 2.1.1)
- Microsoft.Extensions.Http (>= 2.1.1)
- Microsoft.Extensions.Logging.Abstractions (>= 2.1.1)
- Newtonsoft.Json (>= 13.0.1)
- System.Security.Cryptography.Pkcs (>= 4.6.0)
-
net6.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 6.0.0)
- Microsoft.Extensions.Http (>= 6.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 6.0.0)
- Newtonsoft.Json (>= 13.0.1)
- System.Security.Cryptography.Pkcs (>= 6.0.4)
-
net8.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Http (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.0)
- Newtonsoft.Json (>= 13.0.1)
- System.Security.Cryptography.Pkcs (>= 8.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Drop net3.1, add net 8.0.