mirror of
https://github.com/marcogll/passkit-generator.git
synced 2026-03-15 18:25:24 +00:00
Updated documentation
This commit is contained in:
alexandercerutti
28
API.md
28
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)
|
||||
* [<field>.push()](#prop_fields-push)
|
||||
* [<field>.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
|
||||
|
||||
<br><br>
|
||||
<a name="localizing_passes"></a>
|
||||
___
|
||||
|
||||
**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\<Object>**) 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\<Object>**) 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)
|
||||
<br>
|
||||
<br>
|
||||
<a name="prop_fields"></a>
|
||||
___
|
||||
|
||||
**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();
|
||||
|
||||
53
README.md
53
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,20 +40,20 @@ $ 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.<bundle id>",
|
||||
"teamIdentifier": "<here your team identifier>",
|
||||
"organizationName": "<your organization name>",
|
||||
"description": "A localizable description of your pass. To do so, put here a placeholder.",
|
||||
"boardingPass": {}
|
||||
"formatVersion": 1,
|
||||
"passTypeIdentifier": "pass.<bundle id>",
|
||||
"teamIdentifier": "<here your team identifier>",
|
||||
"organizationName": "<your organization name>",
|
||||
"description": "A localizable description of your pass. To do so, put here a placeholder.",
|
||||
"boardingPass": {}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user