Készítsd el az első appodat

Telepítsd a CLI-tHivatkozás másolása

$ npm install -g @poltura/cli

Ellenőrizd a működését:

poltura --help

Hozd létre az appotHivatkozás másolása

poltura app create my-app --template hosted

created hosted app in /Users/you/my-app

A --template native csak a UI workereket hozza létre. A --template hosted emellett létrehozza a src/server.ts fájlt is, amely egy apró Node szerver: a /connect indítja a kapcsolatot, a /oauth/callback fejezi be és olvassa be a boltot, a /webhooks/products pedig az aláírt webhookokat fogadja. A könyvtárnak üresnek kell lennie, vagy még nem létezhet.

Telepítsd a dependencyketHivatkozás másolása

$ cd my-app
$ npm install

A buildhez a react, a react-dom, a @poltura/app-ui és a tailwindcss csomagokra van szükség a projektben. Ezek nélkül a folyamat leáll a Install react in this project to build workers. hibaüzenettel.

Irányítsd az appot a szerveredre és az app-azonosítódraHivatkozás másolása

A poltura.app.json az app manifestje. A scaffold a https://app.example.com címet használja mindenhol; írd át ezeket arra a HTTPS-címre (origin), amelyen a szervered futni fog, és add hozzá az app azonosítóját a Fejlesztői alkalmazások felületről, hogy közzétételkor a rendszer tudja, melyik apphoz tartozik a release:

{
  "schemaVersion": 1,
  "apiVersion": "v1",
  "appId": "0199f3a2-5b1c-7d4e-9f20-3a4b5c6d7e8f", 
  "handle": "my-app",
  "releaseVersion": "1.0.0",
  "displayName": "My App",
  "backendOrigin": "https://app.example.com", 
  "backendOrigin": "https://my-app.example.org", 
  "redirectUrls": ["https://app.example.com/oauth/callback"], 
  "redirectUrls": ["https://my-app.example.org/oauth/callback"], 
}

Módosítsd a supportUrl, privacyUrl, homepageUrl értékeket, és ugyanígy a webhook- és cél-URL-eket is. A handle értékének meg kell egyeznie azzal az Azonosító mezővel, amelyet a Fejlesztői alkalmazások felületen adtál meg az appnak.

A jogosultságok blokkja sorolja fel, hogy az app mit olvas és ír. Minden jogosultsághoz tartozik egy 8 és 280 karakter közötti indoklás (purpose), amelyet a kereskedők a telepítési képernyőn látnak a jóváhagyás előtt:

"permissions": {
  "required": [
    { "id": "settings.read", "purpose": "Read store locale, currency, and public capabilities" },
    { "id": "products.read", "purpose": "List products and collections for the companion admin page" }
  ],
  "optional": []
}

Csak azokat tartsd meg, amelyeket az app használ. A telepítési adatok tárolásához nincs szükség külön jogosultságra. Minden jogosultság megtalálható a Permissions and topics oldalon.

Módosítsd a webáruház-blokkotHivatkozás másolása

A kezdőlapi blokkot egyszer deklarálod a src/elements.ts fájlban. A beállításai mezőkké válnak, amelyeket a kereskedők szerkeszthetnek a témaszerkesztőben, a style lista pedig meghatározza, hogy milyen stílusvezérlőket kapnak:

export const catalogHighlight = defineBlock({
  type: 'catalog-highlight',
  label: 'Catalog highlight',
  description: 'A short catalogue note on the home page.',
  icon: 'sparkles',
  category: 'marketing',
  settings: {
    title: field.text({ label: 'Heading', default: 'Catalog companion' }), 
    title: field.text({ label: 'Heading', default: 'New this week' }), 
    note: field.text({ label: 'Note', default: 'Fresh picks from the catalogue.' }), 
    show_note: field.checkbox({ label: 'Show note', default: true }),
  },
  style: ['spacing', 'background', 'border'],
});

A worker a webáruház alapvető elemeivel (primitives) rajzolja ki, így követi a bolt témáját:

function Home(): ReactNode {
  const settings = useSettings();
  return (
    <Card className='rounded-theme bg-surface text-foreground p-4'>
      <Stack>
        <Heading>{String(settings.title ?? 'Catalog companion')}</Heading>
        {settings.show_note === false ? null : <Text>Storefront home block for this Poltura app.</Text>} {}
        {settings.show_note === false ? null : <Text>{String(settings.note ?? '')}</Text>} {}
      </Stack>
    </Card>
  );
}

Nézd meg, mit definiál most az app:

poltura app elements

catalog-highlight	Catalog highlight	3 settings

Buildeld és ellenőrizdHivatkozás másolása

poltura app build
poltura app validate

built my-app@1.0.0  sha256-dfw5wNzsE0rCJlRiYs68FfVqGAQWsH+I6tStN34IgYI=  2 workers
built my-app@1.0.0  sha256-dfw5wNzsE0rCJlRiYs68FfVqGAQWsH+I6tStN34IgYI=  2 workers
ok my-app@1.0.0
  manifest.json  3906 bytes

A nálad megjelenő hash és méret eltérhet ettől. A build bundle-öli az egyes workereket, compile-olja a src/styles.css fájlt, és a release-t a dist/ mappába írja (a --out kapcsolóval másik könyvtárat választhatsz). A validate egy ideiglenes könyvtárba buildeli a projektet, és ellenőrzi a manifestet, amelyet a felülvizsgálat látni fog. Szerkesztés közben a poltura app dev minden módosításkor recompile-olja a kódot, és a watch <digest> sort írja ki, amikor a release változik.

Tedd közzé felülvizsgálatraHivatkozás másolása

poltura app publish --api "$POLTURA_API" --token "$POLTURA_APP_TOKEN"

published 0199f3b0-1e2d-7a3c-8b4f-5c6d7e8f9a0b

A --api a Poltura API címe (origin), és megadása kötelező; a POLTURA_API környezeti változó beállítása is működik. Az éles címe még nem nyilvános (lásd: Authentication). Add hozzá az --admin-origin <your admin URL> kapcsolót, és a CLI a felülvizsgálati hivatkozást is kiírja. Ha a manifestben kihagytad az appId mezőt, add át a --app <app id> kapcsolót; ennek hiányában a CLI a missing --app <appId> hibával leáll.

Felülvizsgálat és telepítésHivatkozás másolása

A Poltura egy olyan reviewere, aki nem tagja a szervezetednek, pontosan azt a release-t ellenőrzi, amelyet feltöltöttél. Amint jóváhagyja, egy bolt telepítheti is:

1. Futtasd a src/server.ts fájlt a saját HTTPS-címeden a README-ben felsorolt változókkal, majd add ki az npm start parancsot.
2. Nyisd meg a https://my-app.example.org/connect?installation=<installation id> címet a bolt adminisztrátorként. A Poltura megjeleníti a jogosultságokat a megadott indoklásaiddal; hagyd jóvá, és a szerver a Connected to <store name>. üzenettel válaszol.

Az app adminfelületi oldala és kezdőlapi blokkja most már ott van abban a boltban, és a kereskedők elhelyezhetik a blokkot a témaszerkesztőben, mint bármelyik másikat. A közzététel utáni összes teendőt a Ship to merchants oldalon találod.