npm:passkit-generator

README

Simple Node.js interface to generate customized Apple Wallet Passes for iOS and WatchOS.

Architecture

This library was created with a specific architecture in mind: application and model (as preprocessed entity), to split as much as possible static objects (such as logo, background, icon, etc.) from dynamic ones (translations, barcodes, serialNumber, ...), while keeping an eye on the different possible execution contexts.

Pass creation and population might not fully happen in runtime. This library allows to create a pass from scratch, specify a folder model (template) or specify a set of buffers. In the last two cases, both should contain all the objects needed (static medias) and structure to make a pass work.

Whenever adding files, through scratch, template or buffer, these will be read and pushed as they are in the resulting .zip file, while dynamic data will be patched (pass.json with props) or generated in runtime (manifest.json, signature and translation files).

Installation

$ npm install passkit-generator --save

API Documentation

This package comes with an API Documentation Reference, available in wiki, that makes available a series of methods to create and customize passes.

Looking for the previous major version?

Check the v2 tag. That tag is kept for reference only.

Coming from the previous major version?

Look at the Migration Guide.

Getting Started

Model

Assuming that you don't have a model yet, the first thing you'll have to do, is creating one. A model contains all the basic pass data that compose the Pass identity. These data can be files (icon, thumbnails, ...), or pieces of information to be written in pass.json (Pass type identifier, Team Identifier, colors, ...) and whatever you know that likely won't be customized on runtime.

When starting from zero, the best suggested solution is to use a Template (folder) to start with, as it will allow an easier access to all the files and data. Nothing will prevent you using a buffer model or creating a pass from scratch, but they are meant for an advanced usage or different contexts (e.g. running a cloud function might require a scratch model for faster startup, without storing the model in a "data bucket").

Let's suppose you have a file model.zip stored somewhere: you unzip it in runtime and then get the access to its files as buffers. Those buffers should be available for the rest of your application run-time and you shouldn't be in need to read them every time you are going to create a pass.

To maintain a pass model available during the run-time, a PKPass instance can be created from whatever source, and then used as a template through PKPass.from.

Using the .pass extension is a best practice, showing that the directory is a pass package. (Build your first pass - Apple Developer Portal).

Following to this best practice, the package is set to require each folder-model to have a .pass extension. If omitted in the configuration (as in Usage Example, at "model" key), it will be forcefully added.

Model creation can be performed both manually or with the auxiliary of a web tool I developed, Passkit Visual Designer, which will let you design your model through a neat user interface. It will output a .zip file that you can decompress and use as source.

You can follow the Apple Developer documentation (Package Structure) to build a correct pass model. The icon is required in order to make the pass work. Omitting an icon resolution, might make a pass work on a device (e.g. Mac) but not on another (e.g. iPhone). Manifest.json and signature will be automatically ignored from the model and generated in runtime.

You can also create .lproj folders (e.g. en.lproj or it.lproj) containing localized media. To include a folder or translate texts inside the pass, please refer to Localizing Passes in the API documentation.

To include a file that belongs to an .lproj folder in buffers, you'll just have to name a key like en.lproj/thumbnail.png.

Pass.json

Create a pass.json by taking example from examples folder models or the one provided by Apple for the first tutorial and fill it with the basic informations, that are teamIdentifier, passTypeIdentifier and all the other basic keys like pass type. Please refer to Top-Level Keys/Standard Keys and Top-Level Keys/Style Keys.

{
    "formatVersion": 1,
    "passTypeIdentifier": "pass.<bundle id>",
    "teamIdentifier": "<your team identifier>",
    "organizationName": "<your organization name>",
    "description": "A localizable description of your pass. To do so, put here a placeholder.",
    "boardingPass": {}
}

Certificates

The third step is about the developer and WWDR certificates. I suggest you to create a certificate-dedicated folder inside your working directory (e.g. ./certs) to contain everything concerning the certificates.

This is a standard procedure: you would have to do it also without using this library. We'll use OpenSSL to complete our work (or to do it entirely, if only on terminal), so be sure to have it installed.

Follow the FULL GUIDE in wiki to get all the files you need to proceed.

Usage Examples

Folder Model

/**
 * Use `const { PKPass } = require("passkit-generator");`
 * for usage in CommonJS (Node.js)
 */
import { PKPass } from "passkit-generator";

try {
    /** Each, but last, can be either a string or a Buffer. See API Documentation for more */
    const { wwdr, signerCert, signerKey, signerKeyPassphrase } = getCertificatesContentsSomehow();

    const pass = await PKPass.from({
        /**
         * Note: .pass extension is enforced when reading a
         * model from FS, even if not specified here below
         */
        model: "./passModels/myFirstModel.pass",
        certificates: {
            wwdr,
            signerCert,
            signerKey,
            signerKeyPassphrase
        },
    }, {
        // keys to be added or overridden
        serialNumber: "AAGH44625236dddaffbda"
    });

    // Adding some settings to be written inside pass.json
    pass.localize("en", { ... });
    pass.setBarcodes("36478105430"); // Random value

    // Generate the stream .pkpass file stream
    const stream = pass.getAsStream();
    doSomethingWithTheStream(stream);

    // or

    const buffer = pass.getAsBuffer();
    doSomethingWithTheBuffer(buffer);
} catch (err) {
    doSomethingWithTheError(err);
}

Buffer Model

/**
 * Use `const { PKPass } = require("passkit-generator");`
 * for usage in CommonJS (Node.js)
 */
import { PKPass } from "passkit-generator";

try {
    /** Each, but last, can be either a string or a Buffer. See API Documentation for more */
    const { wwdr, signerCert, signerKey, signerKeyPassphrase } = getCertificatesContentsSomehow();

    const pass = new PKPass({
        "thumbnail.png": Buffer.from([ ... ]),
        "icon.png": Buffer.from([ ... ]),
        "pass.json": Buffer.from([ ... ]),
        "it.lproj/pass.strings": Buffer.from([ ... ])
    },
    {
        wwdr,
        signerCert,
        signerKey,
        signerKeyPassphrase,
    },
    {
        // keys to be added or overridden
        serialNumber: "AAGH44625236dddaffbda",
    });

    // Adding some settings to be written inside pass.json
    pass.localize("en", { ... });
    pass.setBarcodes("36478105430"); // Random value

    // Generate the stream .pkpass file stream
    const stream = pass.getAsStream();
    doSomethingWithTheStream(stream);

    // or

    const buffer = pass.getAsBuffer();
    doSomethingWithTheBuffer(buffer);
} catch (err) {
    doSomethingWithTheError(err);
}

For more complex usage examples, please refer to examples folder.

Other

If you used this package in any of your projects, feel free to open a topic in issues to tell me and include a project description or link (for companies). 😊 You'll make me feel like my time hasn't been wasted, even if it had not anyway because I learnt and keep learning a lot of things by creating this.

The idea to develop this package, was born during the Apple Developer Academy 17/18, in Naples, Italy, driven by the need to create an iOS app component regarding passes generation for events.

A big thanks to all the people and friends in the Apple Developer Academy (and not) that pushed me and helped me into realizing something like this and a big thanks to the ones that helped me to make technical choices and to all the contributors.

Any contribution, is welcome. Made with ❤️ in Italy.

Contributors

A big thanks to all the people that contributed to improve this package. Any contribution is welcome. Do you have an idea to make this improve or something to say? Open a topic in the issues and we'll discuss together! Thank you ❤️ Also a big big big big thank you to all the financial contributors, which help me maintain the development of this package ❤️!