What a retailer reads: the card and the guide
Part 3 of 5 · Shipping your own data in a manifest
A manifest has two readers: the installer, which checks it, and the people in the retailer's iVendNext, who decide whether to install the app and what to do next. So write the card and the guide for the retailer's owner or manager, in a retailer's words, not for a developer.
Back: More you can addNext: What is refused, and why
1. The card: what the app does
The card is app.json's card. ivn publish --public asks you once for what it does not hold yet:
"card": {
"title": "Bin locations",
"summary": "Mark where each item sits in a store, by aisle and bin.",
"what": ["Staff record each aisle and bin and what is in it.", "Each item can have a default bin."],
"pictures": ["screenshots/01_workspace.png"],
"industries": ["distribution-and-warehousing", "hardware-and-diy"],
"price": "free",
"guide": "https://github.com/acme/acme-bins#readme"
}
priceisfree, orkey: retailers ask you for a key.industriesnames where the app is especially used; the App library lists the app on each one's page.- Do not say a retailer must create your own roles. The install makes them: say which roles the install adds, and that a person gives them to staff.
- Say what leaves the retailer's iVendNext, from the manifest. If your manifest has an outside address (
allowed_urls), webhooks, till keys, event feeds, services, print formats or label layouts, or an outside service that signs in to read and write, say what it sends or runs outside; do not say nothing leaves your iVendNext.
2. The guide
A page or report of your own registers its help too, with ivendnext_mpos.v1.help_link("query-report/<report>", [{label, url}]), and opens a page with ivendnext_mpos.v1.open_help(url), each guarded by window.ivendnext_mpos && ivendnext_mpos.v1. The guide link may be any https page; your repository's README is enough. A retailer finds its way fastest with five headings, in a retailer's words:
- What it does — two or three sentences; who uses it.
- What you set up first — numbered; each step names the Desk screen by the name a retailer searches for.
- Where it shows — Desk, the till, POS Studio, print layouts.
- What leaves your iVendNext — taken from your manifest: outside addresses, till keys, webhooks, services, event feeds, print and label layouts. Nothing only when the manifest names nothing.
- How to remove it — from the app's Details, Export and uninstall, and what is kept.