diff --git a/API.md b/API.md index eb7801e..85a0536 100644 --- a/API.md +++ b/API.md @@ -16,7 +16,6 @@ Some details: * In case of troubleshooting, you can start your project with "debug flag" as follows: ```sh -$ # Bash terminal $ DEBUG=* node index.js ``` @@ -32,7 +31,7 @@ ___ ### Index: * [Instance](#method_constructor) - * Localize the pass + * [Localizing Passes](#localizing_passes) * [.localize()](#method_localize) * Setting barcode * [.barcode()](#method_barcode) @@ -45,7 +44,7 @@ ___ * [.relevance()](#method_relevance) * Setting NFC * [.nfc()](#method_nfc) - * Setting Pass Structure Keys (primaryFields, secondaryFields, ...) + * [Setting Pass Structure Keys (primaryFields, secondaryFields, ...)](#prop_fields) * [.push()](#prop_fields-push) * [.pop()](#prop_fields-pop) * [TransitType](#prop_transitType) @@ -83,9 +82,10 @@ var pass = new Pass(options); | options.shouldOverwrite | Boolean | Setting this property to false, will make properties in `overrides` and fields to be pushed along with the ones added through methods to the existing ones in pass.json. | true | true

+ ___ -**Localize the pass**: +**Localizing Passes**: ___ Following Apple Developer Documentation, localization (L10N) is done by creating a `.lproj` folder for each language you want to translate your pass, each named with the relative [ISO-3166-1 alpha-2](https://it.wikipedia.org/wiki/ISO_3166-1_alpha-2) code (e.g. `en.lproj`). @@ -334,7 +334,7 @@ pass.relevance(key, value [, relevanceDateFormat]); It sets the relevance key in the pass among four: **beacons**, **locations**, **relevantDate** and **maxDistance**. See [Apple Documentation dedicated page](https://apple.co/2QiE9Ds) for more. -For the first two keys, the argument 'value' (which will be of type **Array\**) will be checked and filtered against a schema (one for type). +For the first two keys, the argument 'value' (which will be of type **Array\**) will be checked and filtered against dedicated schema. For *relevantDate*, the date is parsed in the same formats of [#expiration()](#method_expiration). For *maxDistance*, the value is simply converted as Number and pushed only with successful conversion. @@ -398,6 +398,7 @@ An Object as argument will be treated as one-element array. **See**: [PassKit Package Format Reference # NFC](https://apple.co/2wTxiaC)

+ ___ **Setting Pass Structure Keys (primaryFields, secondaryFields, ...)**: @@ -434,15 +435,15 @@ Fields are filtered against a schema. ```javascript pass.headerFields.push({ - "key": "header1", - "label": "Data", - "value": "25 mag", - "textAlignment": "PKTextAlignmentCenter" + key: "header1", + label: "Data", + value: "25 mag", + textAlignment: "PKTextAlignmentCenter" }, { - "key": "header2", - "label": "Volo", - "value": "EZY997", - "textAlignment": "PKTextAlignmentCenter" + key: "header2", + label: "Volo", + value: "EZY997", + textAlignment: "PKTextAlignmentCenter" }); pass.primaryFields.push({ @@ -536,7 +537,6 @@ The returned Promise will contain a stream or an error. **Examples**: ```javascript -... pass.generate() .then(stream => { doSomethingWithPassStream(); diff --git a/README.md b/README.md index 8dfc7f9..bea0d90 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,37 @@ # Node PassKit Generator -This is my implementation of a generator for [Apple Wallet Passes](https://developer.apple.com/wallet/). The idea was born during the Apple Developer Academy 17/18, in Naples, driven by the need to develop an iOS app component regarding passes generation for events. +Simple Node.js interface to generate customized [Apple Wallet Passes](https://developer.apple.com/wallet/) for iOS. +### Architecture -### Installation -This generator has two sides: application and model creation. +This package was created with a specific architecture in mind: **application** and **model**, to split as much as possible static objects (such as logo, background, icon, etc.) from dynamic ones (translations, barcodes, serialNumber, ...). -In fact, the pass template creation does not happen in the application. Instead you'll first have to create a folder containing all the static medias for a pass (logo, background, icon, etc.) while the dynamic info (such translations, barcodes, serialNumber and so on) will be applied in runtime. +In fact, pass template (model) creation and population doesn't happen within the application in runtime. Pass template is a folder in _your application directory_ (but nothing will stop you from putting it outside), that will contain all the needed objects (static medias) and structure to make a pass work. +Pass template will be read and pushed as is in the resulting .zip file, while dynamic objects will be patched against `pass.json` or generated in runtime (`manifest.json`, `signature` and translation files). + +This package comes with an [API documentation](./API.md), that makes available a series of methods to customize passes. + +### Install ```sh $ npm install passkit-generator --save ``` -To see the API Reference, please refer to [API document](./API.md). -Created under Node.js v10.8.0. +### Compatibility +This package is compatible starting with Node v8.1.0+. + +___ ## Get Started +##### Model + The first thing you'll have to do, is to start creating a model. A model is a folder in your project directory, with inside the basic pass infos, like the thumbnails, the icon, and the background and **pass.json** containing all the static infos about the pass, like Team identifier, Pass type identifier, colors, etc. > Using the .pass extension is a best practice, showing that the directory is a pass package. -> (cit. [Build your first pass - Apple Developer Portal](https://apple.co/2LYXWo3)). +> ([Build your first pass - Apple Developer Portal](https://apple.co/2LYXWo3)). -Following to this suggestion, each model is required to have a **.pass** extension (as suggested by Apple). +Following to this suggestion, each model is required to have a **.pass** extension. ```bash $ cd yourProjectDir; @@ -31,25 +40,25 @@ $ mkdir passModels && mkdir $_/myFirstModel.pass && cd $_; Follow the [Apple Developer documentation](https://apple.co/2wuJLC1) (_Package Structure_) to build a correct pass model. The **icon is required** in order to make the pass work. *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 the API, [.localize()](./API.md#method_localize) method. +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](./API.md#method_localize) in the API documentation. ##### Pass.json Create a `pass.json` by taking example from examples folder models or the one provided by Apple for the [first tutorial](https://apple.co/2NA2nus) and fill it with the basic informations, that is `teamIdentifier`, `passTypeIdentifier` and all the other basic keys like pass type. Please refer to [Top-Level Keys/Standard Keys](https://apple.co/2PRfSnu) and [Top-Level Keys/Style Keys](https://apple.co/2wzyL5J). -```javascript +```json { - "formatVersion": 1, - "passTypeIdentifier": "pass.", - "teamIdentifier": "", - "organizationName": "", - "description": "A localizable description of your pass. To do so, put here a placeholder.", - "boardingPass": {} + "formatVersion": 1, + "passTypeIdentifier": "pass.", + "teamIdentifier": "", + "organizationName": "", + "description": "A localizable description of your pass. To do so, put here a placeholder.", + "boardingPass": {} } ``` ##### Certificates -> Requirements: OpenSSL, +> Requirements: OpenSSL, 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. You'll need the following three elements: @@ -74,6 +83,7 @@ While WWDR can be obtained from [Apple PKI Portal](https://www.apple.com/certifi ``` 7. Execute step 5 also for the WWDR certificate (`.cer`) you downloaded from Apple PKI portal (default name: *AppleWWDRCA.cer*) but instead exporting it as PKCS#12 (`.p12` - you'll also be unable to do that), export it as PEM (`.pem`) file. +___ ## Usage example @@ -113,10 +123,15 @@ pass.generate() }); ``` +___ + ## Other -If you developed any projects using this library, open an issue topic and link it inside if open to all or just tell it. 😊 You'll make me feel like my time hasn't been wasted (it had not anyway, I learnt a lot of things by doing this). +If you developed any public projects using this library, open a topic in issues and link it inside if open to all or just tell it. 😊 You'll make me feel like my time hasn't been wasted (it had not anyway, I learnt a lot of things by doing this). Be sure to not include the certificates if you publish your project open to everybody. -Any contribution is welcome ❤️ -A big thanks to all the people and friends in the Apple Developer Academy 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. +Any contribution is welcome. ❤️ + +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.