Manifest

A poltura.app.json az app-projekted gyökerében található, és leír mindent, amit a Polturának tudnia kell az appról: mi az, milyen boltadatokat kér el, hol fut a szervere, mit rajzol ki az adminfelületen és a webáruházban, valamint milyen eseményeket és műveleteket kezel. A poltura app build ellenőrzi, kötegeli a workerjeidet, és létrehozza a release manifestet (dist/manifest.json). Ezt a fájlt hagyja jóvá a bíráló, és ezt telepíti a kereskedő.

A CLI szándékosan szigorú:

• Az ismeretlen mezők hibát okoznak. Egy elírás, mint a redirectUrl (a redirectUrls helyett), hibát jelez, nem pedig csendben figyelmen kívül hagyott beállítás.
• A platform belső működésére vagy hitelesítő adatokra hasonlító nevek hibát okoznak, bárhol is szerepelnek: olyan kulcsok vagy azonosítók, mint a token, secret, api_key, password, database, query, code vagy workflow. Egy app soha nem kap hozzáférést a platform belső felületeihez, így a manifestben sincs mód ilyet kérni.
• A hibaüzenetek megnevezik a mezőt. A CLI kiírja az elérési utat és az indokot, például: app config schema: permissions.required.0.purpose: purpose must explain the merchant-visible use. A 0 a lista első eleme.

Egy teszt folyamatosan összeveti ezt az oldalt a CLI sémájával: a táblázatok minden sorát, a kötelező jelöléseket, az alapértelmezéseket és az alábbi összes JSON-példát, amelyeket egy valós manifest részeként el kell fogadnia. Egy mezőt sem lehet úgy hozzáadni vagy eltávolítani, hogy ez az oldal ne változzon. A Kötelező jelölés a szülőjén belül kötelezőt jelent: az actions[].id minden műveletben kötelező, de maga az actions nem kötelező.

Egy rövid manifestHivatkozás másolása

Ez a natív widgetes példa (Parcel helper) teljes manifestje: két adminpanel és két művelet. Minden, ami nincs felsorolva, az alapértelmezett értékét veszi fel. A lejjebb található rövidebb JSON-példák egy ilyen manifest részletei.

{
  "schemaVersion": 1,
  "apiVersion": "v1",
  "handle": "parcel-helper",
  "releaseVersion": "1.0.0",
  "displayName": "Parcel helper",
  "description": "Suggests a box size on order pages and checks product listings before they go live.",
  "translations": [
    {
      "locale": "hu-HU",
      "displayName": "Csomagsegéd",
      "description": "Dobozméretet javasol a rendeléseknél, és ellenőrzi a termékoldalakat élesítés előtt."
    }
  ],
  "supportUrl": "https://parcel-helper.example.com/support",
  "privacyUrl": "https://parcel-helper.example.com/privacy",
  "backendOrigin": "https://parcel-helper.example.com",
  "redirectUrls": ["https://parcel-helper.example.com/oauth/callback"],
  "permissions": {
    "required": [
      {
        "id": "orders.read",
        "purpose": "Read the items of the order you have open to suggest a box"
      },
      {
        "id": "products.read",
        "purpose": "Read the product you have open to check its listing"
      }
    ],
    "optional": []
  },
  "actions": [
    {
      "id": "suggest_box",
      "purpose": "Suggest a box size from the items of the open order",
      "surfaces": ["admin"]
    },
    {
      "id": "check_listing",
      "purpose": "Check the title, description and image of the open product",
      "surfaces": ["admin"],
      "timeoutMs": 3000
    }
  ],
  "workers": [
    {
      "target": "admin.order",
      "entry": "src/workers/order-panel.tsx",
      "stylesheet": "src/styles.css"
    },
    {
      "target": "admin.product",
      "entry": "src/workers/product-panel.tsx",
      "stylesheet": "src/styles.css"
    }
  ]
}

A mezők funkciójuk szerint csoportosítva:

IdentitásHivatkozás másolása

• A schemaVersion és apiVersion a manifest formátumát és az App API verzióját jelöli, amelyre az app készült. Jelenleg csak ezek az értékek fogadhatók el.
• A handle az appod állandó azonosítója. Pontosan meg kell egyeznie az Azonosító mezővel, amelyet az app létrehozásakor megadtál a Fejlesztői alkalmazások felületén; közzétételkor minden más azonosítójú release-t elutasít a rendszer. Ezt később nem módosíthatod.
• A releaseVersion azonosítja a release-t a bírálók és a kereskedők számára. Minden közzétett release-hez használj új verziót, hogy meg tudd különböztetni őket.
• A displayName és description jelenik meg a kereskedőknek a jogosultsági képernyőn és a telepített appok listájában.
• A translations más nyelveken adja meg a nevet és a leírást. Minden elemnek tartalmaznia kell a displayName, a description mezőt vagy mindkettőt, és minden locale csak egyszer szerepelhet.
• Az appId mezőt csak a CLI olvassa: a poltura app publish ezt használja, ha elhagyod a --app kapcsolót. Nem másolódik át a release manifestbe.

{
  "handle": "parcel-helper",
  "releaseVersion": "1.2.0",
  "displayName": "Parcel helper",
  "description": "Suggests a box size on order pages.",
  "translations": [{ "locale": "hu-HU", "displayName": "Csomagsegéd" }],
  "appId": "0199f3a2-5b1c-7d4e-9f20-3a4b5c6d7e8f"
}

Gyakori hibák:

• A "handle": "Parcel-Helper" hibát jelez: handle must be lowercase letters and digits joined by single hyphens.
• A "releaseVersion": "v1.0.0" hibát jelez: must be a semver release without build metadata. Ugyanez igaz az 1.0.0+build.5 formátumra is.
• A csak locale mezőt tartalmazó fordítás hibát jelez: translation must include displayName or description.

Hivatkozások és a szerveredHivatkozás másolása

• A supportUrl és privacyUrl megjelenik a bírálóknak és a kereskedőknek. Az adatvédelmi oldalnak ismertetnie kell, milyen boltadatokat tárolsz és mennyi ideig.
• A backendOrigin a te szervered. Ide érkeznek a műveletek (lásd: actions).
• A redirectUrls tartalmazza azokat a címeket, amelyekre a Poltura visszairányíthatja a kereskedőt a kapcsolódás végén. A redirectUri, amelyet a szervered átad az SDK OAuth-kliensének, karakterről karakterre egyeznie kell valamelyikkel. A lista akkor is kötelező, ha az app soha nem hívja meg az App API-t; állítsd be arra a visszahívási útvonalra, amelyet használnál. Lásd: Hitelesítés.

Minden URL-t a pontos kanonikus formájában kell megadni, ahogyan a böngésző kiírná. Ez kiszűr néhány váratlan hibát:

• Az önmagában álló origin végére kötelező a perjel: a "homepageUrl": "https://parcel-helper.example.com" elutasításra kerül a következő hibával: HTTPS URL must be the exact canonical href; írd így: https://parcel-helper.example.com/.
• A hosztnevek csupa kisbetűsek, az alapértelmezett portok elmaradnak, és nincs bennük #fragment, felhasználónév vagy jelszó.
• A http:// hibát okoz, ahogyan a helyettesítő karakterek is (például https://*.example.com/callback).
• A "backendOrigin": "https://parcel-helper.example.com/api" hibát jelez: backend origin must not include a path or query.

Bolti hozzáférésHivatkozás másolása

A jogosultság lehetővé teszi, hogy az appod az App API-n keresztül olvasson vagy módosítson egy adott típusú boltadatot. Ezek megegyeznek azokkal a jogosultságokkal, amelyeket a kereskedők a csapattagjaiknak adnak. A kereskedő a jóváhagyás előtt a telepítési képernyőn látja az összes jogosultságot az általad megadott purpose leírással, és az összes required jogosultságot megadja. Az optional jogosultságokat elutasíthatja, ezért mielőtt olyan API-t hívnál, amelyhez szükség lenne rájuk, ellenőrizd, mit hagyott jóvá a kereskedő (lásd: Hitelesítés). Ha az app nem olvas boltadatokat, nem kell jogosultságot kérnie.

A célt a kereskedő szemszögéből, a boltjára vonatkoztatva fogalmazd meg: „A megnyitott rendelés tételeinek olvasása a dobozméret javaslatához”, ne pedig így: „Az API-hoz szükséges”.

"permissions": {
  "required": [{ "id": "products.read", "purpose": "List your products to pick featured ones" }],
  "optional": [{ "id": "products.write", "purpose": "Mark your featured products in the catalog" }]
}

Gyakori hibák:

• Az optional elhagyása: mindkét lista kötelező, ezért írd így: "optional": [].
• Ugyanaz a jogosultság mindkét listában, vagy kétszer ugyanabban a listában hibát jelez: permission "orders.read" cannot be both required and optional.
• A kötelező írási jogosultság magában foglalja az olvasást is, így az olvasás nem lehet nem kötelező: a products.read egy kötelező products.write mellett hibát jelez: permission "products.read" comes with the required "products.write" and cannot be optional.
• A 8 karakternél rövidebb cél hibát jelez: purpose must explain the merchant-visible use.
• Olyan azonosító, amely nem szerepel a katalógusban, például products:read kettősponttal a products.read helyett.
• Több jogosultság kérése, mint amennyit az app ténylegesen használ. A bíráló és a kereskedő minden jogosultságot lát; csak azt kérd, amire az appnak valóban szüksége van.

Admin- és webáruház-felületHivatkozás másolása

workersHivatkozás másolása

A worker a natív kezelőfelület egy része, amelyet Reactben írsz a Poltura komponenseivel, és a CLI bundle-özi. Mindegyik worker egy adott célterületre (target) renderelődik: egy helyre az adminfelületen vagy a webáruházban.

• A projekthez szükséges a workers lista, vagy helyette a speciális uiRuntime és sources páros. Minden appnak van legalább egy workere; a kizárólag hosztolt felületű appok is tartalmaznak egy kisebb workert, például egy kezdőképernyős kártyát.
• A target határozza meg, hol jelenik meg a worker. Az adminisztrációs célok oldalak, a kezdőlap, valamint a termékek, gyűjtemények, rendelések és vásárlók részletező paneljei. A webáruházi célok a sablonra helyezhető blokkok, a header- és lábléczónák, valamint az appoldalak. Lásd: Adminfelület és Webáruház.
• A stylesheet a Tailwinddel fordul le, és bekerül a release-be. Bekapcsolt inheritTheme mellett a gazdafelület színei, betűtípusai, lekerekítései, árnyékai és térközei átadódnak a worker stílusainak, így illeszkedik az adminfelülethez vagy a bolt témájához. Lásd: Stílusok.
• Az element összekapcsolja a webáruházi blokk-workert a defineBlock definícióval, amely nevet, ikont és beállításokat ad neki a témaszerkesztőben. Kötelező a webáruházi sabloncélokhoz, valamint a header- és lábléczónákhoz, és nem kötelező a storefront.app-page és adminisztrációs célok esetén.

elementsHivatkozás másolása

A defineBlock hívásokat tartalmazó fájlok. A build futtatás nélkül olvassa őket, és megáll a fájl, sor és oszlop megjelölésével, ha valamelyik definíciót nem tudja értelmezni. Lásd: Beállítások és fordítások.

adminPagesHivatkozás másolása

Egy admin.page worker önmagában nem érhető el. Ha itt felsorolod, bekerül az admin-navigáció Alkalmazások csoportjába, a /apps/<installation id>/<page id> címen. Az adminfelület annak a fordításnak a címét jeleníti meg, amelynek a locale értéke pontosan egyezik a kereskedő nyelvével, majd az azonos nyelvűt (hu-HU esetén hu), végül a title mezőt.

Oldalikonok: home, box, boxes, cart, receipt, users, user, tag, settings, chart, globe, mail, file, files, image, link, star, heart, grid, list, search, bell, calendar, message.

storefrontPagesHivatkozás másolása

A webáruházi oldalt a kereskedő boltjában a /apps/<slug> route-on szolgálja ki a rendszer. Hagyd az indexable mezőt kikapcsolva, kivéve, ha az oldal olyan tartalmat hordoz, amelyet a keresőknek indexelniük kell. Ezeket a slugokat a bolt már használja, így nem adhatók meg: products, cart, checkout, account, profile, blog, guides, legal, contact, faq, claim, review, order, auth, pages, apps, api, sitemap, robots.

"workers": [
  { "target": "admin.page", "entry": "src/workers/settings-page.tsx" },
  { "target": "storefront.app-page", "entry": "src/workers/wishlist.tsx", "element": "wishlist-page" }
],
"elements": "src/elements.ts",
"adminPages": [{ "id": "settings", "path": "workers/settings-page.js", "title": "Settings", "icon": "settings" }],
"storefrontPages": [
  {
    "id": "wishlist",
    "path": "workers/wishlist.js",
    "title": "Wishlist",
    "slug": "wishlist",
    "translations": [{ "locale": "hu-HU", "title": "Kívánságlista" }]
  }
]

Gyakori hibák:

• Az element nélküli webáruházi blokk-worker hibát jelez: worker storefront.home is a block merchants place: name its defineBlock type in "element".
• Az element mező az elements megadása nélkül hibát jelez: "element": "parcel" needs "elements" pointing at the files with its defineBlock call.
• Az oldal path mezője, ha nem lefordított worker-útvonalra mutat, hibát jelez: admin page "parcel" path "workers/parcel.js" must match a uiRuntime worker whose target is admin.page. A lefordított elérési út a workers/ mappa és a belépési fájl neve .js kiterjesztéssel, hacsak a worker nem ad meg saját path értéket.
• A "slug": "cart" hibát jelez: slug "cart" is reserved.
• A címek egyszerű szövegek: a HTML-tagek, a javascript: és a hasonlók nem megengedettek.

adminFrameHivatkozás másolása

A hosztolt oldal egy olyan oldal, amelyet a saját szerveredről szolgálsz ki, és az adminfelületen belül egy iframe-ben jelenik meg. Akkor érdemes választani, ha saját HTML-re és JavaScriptre van szükséged. Az actions listázza, hogy az oldal mire kérheti meg az adminfelületet: toast, set_loading, navigate_host, pick_resource, resize, get_session_token és get_appearance. Add hozzá a get_session_token értéket, ha az oldal hívásokat indít a szervered felé; lásd: Hitelesítés.

"adminFrame": { "url": "https://catalog-glance.example.com/app", "actions": ["get_session_token"] }

A localhost, *.localhost és az IP-címek hibát jeleznek: App pages require a public HTTPS hostname.. A hosztolt oldalakat valódi HTTPS-hosztnéven teszteld, például tunnelön keresztül.

Szerverhívások és eseményekHivatkozás másolása

actionsHivatkozás másolása

A művelet egy natív workerből a szervered felé indított hívás. A worker meghívja a useAction('suggest_box') függvényt, a platform aláírja a kérést és elküldi a szerveredre, a szervered válasza pedig visszajut a workerhez. A szervered soha nem kapja meg a kereskedő hitelesítési adatait, a worker pedig soha nem kapja meg a tieidet.

• A surfaces határozza meg, honnan hívhatják a workerek a műveletet. A webáruházi hívás a vásárló adatait is továbbítja.
• A timeoutMs azt adja meg, hogy a platform mennyi ideig vár a szervered válaszára, mielőtt a worker hívása meghiúsulna.
• A maxInputBytes és maxOutputBytes korlátozza az oda-vissza küldött JSON méretét; csökkentsd őket a művelet valós igényeihez.

A műveletek szerveroldali fogadásáról és ellenőrzéséről a createActionHandler használatával a Hitelesítés oldalon olvashatsz.

Gyakori hibák: az "id": "suggestBox" hibát jelez: action id must be snake_case; a "timeoutMs": 20000 hibát ad: Number must be less than or equal to 10000; az "id": "token" nem engedélyezett: action id "token" is not allowed; a ?, #, .. vagy // karaktereket tartalmazó route hibát jelez: action path must be relative to backendOrigin.

webhooksHivatkozás másolása

A Poltura aláírt POST kérést küld a destination címre, amikor az esemény bekövetkezik egy olyan boltban, amely telepítette az appodat. Minden témához szükség van az adatai olvasásához tartozó jogosultságra: az order.* témákhoz az orders.read kell. Az app.* lifecycle eventekhez nem szükséges jogosultság. Minden téma és minden célcím legfeljebb egyszer szerepelhet. Lásd: Webhookok.

destinationsHivatkozás másolása

A te oldaladon lévő egyéb címek, amelyek boltadatokat fogadnak; deklarálni kell őket, hogy a jóváhagyásra benyújtott release részét képezzék. A Poltura ellenőrzi és eltárolja őket, de jelenleg nem küld rájuk adatot. Az azonosítóknak és az URL-eknek egyedinek kell lenniük.

Appszintű beállításokHivatkozás másolása

A Poltura ellenőrzi ezeket a mezőket és a release-zel együtt tárolja őket, de jelenleg még egyetlen adminképernyő sem jeleníti meg őket. A kereskedő által ma szerkeszthető beállítások a workerhez tartoznak: a defineBlock definícióból származnak, és a useSettings() függvénnyel olvashatók be. Lásd: Beállítások és fordítások.

Gyakori hiba: ha az enum típusú mező default értéke nem szerepel az options listában, hibát ad: enum default must be one of the options.

Bejelentkezési szolgáltatókHivatkozás másolása

A bejelentkezési appok segítségével a vásárlók külső fiókkal (például Google vagy Discord) jelentkezhetnek be az áruházba. A Poltura saját bejelentkezési appjai az identity_provider mezőben deklarálják a szolgáltatójukat a manifestjükben; az ezen az oldalon található poltura.app.json formátum ezt még nem fogadja el, így a közzétett appok nem adhatnak hozzá ilyet.

• A kereskedő a saját hitelesítési adatait hozza. Létrehoz egy klienst a szolgáltatónál, majd megadja annak azonosítóját (id) és titkos kulcsát (secret) az app beállításaiban. A secret soha nem jut el a vásárló böngészőjébe.
• Egyetlen átirányítási cím. Az app beállítási lépései megjelenítik azt az egyetlen átirányítási címet, amelyet a kereskedő regisztrál a szolgáltatónál.
• Alkalmazásonként egy gomb. Amíg az alkalmazás telepítve és engedélyezve van, valamint mindkét hitelesítési adat be van állítva, a webáruház felületén megjelenik hozzá egy bejelentkezési gomb, amint a regisztráció megerősítésre kerül – ez a módosítás után akár egy percet is igénybe vehet. Az alkalmazás kikapcsolása, eltávolítása vagy valamelyik hitelesítési adat törlése eltávolítja a gombot.
• Sablonok. A gombokat a SocialSignIn part rajzolja ki; a providers propja app id alapján korlátozza őket, mint például az auth-google.
• A vásárló címe. Az a vásárló, akinek a címét a szolgáltató igazolja, közvetlenül bejelentkezik. Ha már létezik fiók ezzel a címmel, vagy a szolgáltató nem igazolja a címet, először egy kód érkezik e-mailben erre a címre. Ha a szolgáltató nem ad vissza címet, a webáruház rákérdez egyre, és ugyanígy igazoltatja azt.

SpeciálisHivatkozás másolása

A legtöbb appnak ezekre soha nincs szüksége.

• Az extensions elemek deklaratív dokumentumok: egyszerű oldalt vagy blokkot leíró JSON, kód nélkül. Az új appok workereket használnak.
• Az uiRuntime és sources párossal te magad adhatod meg a release route-okat ahelyett, hogy a workers képezné le őket:

"uiRuntime": {
  "version": 1,
  "workers": [{ "target": "storefront.home", "path": "workers/home.js", "element": "home-offer" }]
},
"sources": { "workers/home.js": "src/workers/storefront-home.tsx" },
"elements": "src/elements.ts"

Release-korlátokHivatkozás másolása

• Release-enként 16 worker, bundle-önként legfeljebb 1 MiB méretben, stylesheetenként legfeljebb 256 KiB méretben.
• A release manifest legfeljebb 256 KiB, és a teljes release feltöltése legfeljebb 22 MiB lehet.
• Egy appnak egyszerre egy release-e lehet bírálat alatt.

Egy teljes példaHivatkozás másolása

A példaalkalmazás bemutatójának manifestje öt workerrel, műveletekkel, webhookokkal és oldalakkal:

{
  "schemaVersion": 1,
  "apiVersion": "v1",
  "handle": "recommendations",
  "releaseVersion": "1.0.0",
  "displayName": "Recommendations by Poltura Labs",
  "description": "Product recommendations for admin settings, product panels, storefront blocks, footer capture, and an app-owned page.",
  "translations": [
    {
      "locale": "hu-HU",
      "displayName": "Ajánlások a Poltura Labs-tól",
      "description": "Termékajánlók az adminhoz, a termékoldalhoz, a lábléchez és egy alkalmazásoldalhoz."
    }
  ],
  "supportUrl": "https://recommendations.apps.example.com/support",
  "privacyUrl": "https://recommendations.apps.example.com/privacy",
  "homepageUrl": "https://recommendations.apps.example.com/",
  "backendOrigin": "https://recommendations.apps.example.com",
  "redirectUrls": ["https://recommendations.apps.example.com/oauth/callback"],
  "permissions": {
    "required": [
      {
        "id": "settings.read",
        "purpose": "Read store locale, currency, and public capabilities"
      },
      {
        "id": "products.read",
        "purpose": "List products and collections used as recommendation sources"
      },
      {
        "id": "orders.read",
        "purpose": "Read new orders that refresh recommendation weights"
      }
    ],
    "optional": []
  },
  "webhooks": [
    {
      "topic": "order.created",
      "destination": "https://recommendations.apps.example.com/webhooks/orders"
    },
    {
      "topic": "product.updated",
      "destination": "https://recommendations.apps.example.com/webhooks/products"
    }
  ],
  "settings": [
    {
      "id": "highlight_mode",
      "type": "enum",
      "label": "Highlight mode",
      "options": ["quiet", "featured"],
      "default": "quiet"
    }
  ],
  "actions": [
    {
      "id": "save_featured",
      "purpose": "Save featured product ids for this installation",
      "surfaces": ["admin"]
    },
    {
      "id": "recommend",
      "purpose": "Return a product recommendation for the current shopper",
      "surfaces": ["storefront"]
    }
  ],
  "destinations": [
    {
      "id": "newsletter_capture",
      "url": "https://recommendations.apps.example.com/capture",
      "purpose": "Receive optional newsletter captures from the footer worker"
    }
  ],
  "adminPages": [
    {
      "id": "recommendations",
      "path": "workers/admin-page.js",
      "title": "Recommendations",
      "translations": [
        {
          "locale": "hu-HU",
          "title": "Ajánlások"
        }
      ],
      "icon": "star"
    }
  ],
  "storefrontPages": [
    {
      "id": "recs_page",
      "path": "workers/app-page.js",
      "title": "Recommendations",
      "slug": "recommendations",
      "translations": [
        {
          "locale": "hu-HU",
          "title": "Ajánlások"
        }
      ],
      "icon": "star"
    }
  ],
  "elements": "src/elements.ts",
  "workers": [
    {
      "target": "admin.page",
      "entry": "src/workers/admin-page.tsx",
      "stylesheet": "src/styles.css",
      "element": "recommendations-panel"
    },
    {
      "target": "admin.product",
      "entry": "src/workers/admin-product.tsx",
      "stylesheet": "src/styles.css"
    },
    {
      "target": "storefront.product",
      "entry": "src/workers/storefront-product.tsx",
      "stylesheet": "src/styles.css",
      "element": "recommendations"
    },
    {
      "target": "storefront.layout.footer",
      "entry": "src/workers/storefront-footer.tsx",
      "stylesheet": "src/styles.css",
      "element": "newsletter-capture"
    },
    {
      "target": "storefront.app-page",
      "entry": "src/workers/app-page.tsx",
      "stylesheet": "src/styles.css",
      "element": "recommendations-page"
    }
  ]
}

További lépésekHivatkozás másolása

• Hitelesítés: OAuth, session tokenek és aláírt műveletek, amelyekre a fenti mezők közül több is hivatkozik.
• Kezelőfelület: mit érdemes elhelyezni egy workerben.