Widgetek beágyazása

A Komashi-widgetekkel kész szolgáltatásválasztó vagy előfizetési felületet jeleníthetsz meg a saját weboldaladon. A tartalom a Komashiban rögzített beállításokból származik; a betöltő egy iframe-et helyez el ott, ahová a szkriptet beilleszted.

Widget	Mire használható?	Kötelező erőforrás-azonosító
Szolgáltatásválasztó / Service Picker	Egy szolgáltatás csomagjainak megjelenítése és előfizetési folyamat indítása.	`data-service-id`
Előfizetés részletei / Subscription Details	Egy konkrét, meglévő előfizetés megjelenítése és kezelése.	`data-subscription-id`

A Vezérlőközpont → Integráció → Widgetek oldalon mindkettőt megtekintheted, és kimásolhatod a beágyazókódját. A felület működését és az üres állapotokat a Widgetek beállításai útmutató mutatja be.

Szolgáltatásválasztó beágyazása

Másold a szkriptet a HTML-be oda, ahol a widgetnek meg kell jelennie:

<script
  src="https://komashi.com/widget/embed.js"
  data-komashi-widget
  data-service-id="YOUR_SERVICE_ID"
  data-view="service-picker"
></script>

A YOUR_SERVICE_ID helyére valódi szolgáltatásazonosítót adj meg a REST API-ból vagy más megbízható Komashi-erőforrásból. A generált példa helyőrzőt tartalmaz: változtatás nélkül bemásolva nem kapcsolja be a szolgáltatásodat.

A saját környezetedhez generált szkriptcímet használd. Nyilvános weboldalon ne a helyi komashi-app.test cím szerepeljen.

Előfizetés részleteinek beágyazása

Annak az ügyfélnek az előfizetés-azonosítóját add át, aki jogosult az adott előfizetés megtekintésére:

<script
  src="https://komashi.com/widget/embed.js"
  data-komashi-widget
  data-subscription-id="YOUR_SUBSCRIPTION_ID"
  data-view="subscription-details"
></script>

Egyedi előfizetés-azonosítót használj, ne csoportazonosítót. A widget ebből határozza meg a szolgáltatást és a szolgáltatót. Az ügyfélazonosító nem helyettesíti a kötelező előfizetés-azonosítót.

A HTML-ben átadott azonosítók a böngésző számára láthatók. A saját szervereden döntsd el, hogy a bejelentkezett látogató melyik ügyfélhez és előfizetéshez férhet hozzá. Egy URL-ből kimásolt tetszőleges azonosító önmagában nem igazolja a jogosultságot.

Beágyazási attribútumok

Attribútum	Jelentés
`src`	A generált `/widget/embed.js` URL.
`data-komashi-widget`	A Komashi-betöltő számára megjelöli a beágyazást.
`data-view`	Kifejezetten `service-picker` vagy `subscription-details` értéket adj meg.
`data-service-id`	A Szolgáltatásválasztóhoz szükséges szolgáltatásazonosító.
`data-subscription-id`	Az Előfizetés részletei nézethez szükséges előfizetés-azonosító.
`data-customer-id`	Opcionális meglévő ügyfélkörnyezet; csak az integrációhoz megfelelő ügyfelet add meg.
`data-redirect-url`	Opcionális visszatérési cím a támogatott, befejezett folyamatokhoz. Saját kezelésű abszolút URL-t használj.
`data-is-preview`	A Vezérlőközpont példájának előnézeti módja. Éles ügyfélbeágyazásból hagyd ki.

Szolgáltatói API-kulcs nem kerülhet a szkriptbe. A REST-kulcsot a szervereden tárold.

Példa Szolgáltatásválasztóra visszatérési címmel:

<script
  src="https://komashi.com/widget/embed.js"
  data-komashi-widget
  data-service-id="YOUR_SERVICE_ID"
  data-view="service-picker"
  data-redirect-url="https://your-website.example/thanks"
></script>

A visszatérési cím elérése nem igazolja a fizetés sikerét. Ha a saját alkalmazásod hozzáférést ad, kérdezd le az előfizetés állapotát.

Elrendezés és betöltés

Az iframe a befogadó elem teljes szélességét kitölti. A betöltő és a widget a tartalom magasságát egyeztetve méretezi át a felületet. A widget a szolgáltató beállított nyelvét használja.

Ha a weboldal Content Security Policy szabályai korlátozzák a külső szkripteket vagy iframe-eket, engedélyezd bennük a widget domainjét. A fizetési folyamat külön oldalt is nyithat; a normál navigációt és az ilyen ablaknyitást tartsd működőképesen.

Több widgetnél minden megjelölt szkriptelem szerepeljen a HTML-ben a betöltő első futása előtt. A jelenlegi betöltő az első futáskor megtalált elemeket inicializálja; az egyoldalas alkalmazás által később beszúrt beágyazások automatikus újrafelderítésére nincs dokumentált felület.

Hibaelhárítás

Probléma	Mit ellenőrizz?
Üres vagy nem elérhető widget	Cseréld ki a helyőrző azonosítót, ellenőrizd a `data-view` értékét és az erőforrás létezését.
Helyben működik, nyilvános oldalon nem	Helyi `.test` cím helyett nyilvánosan elérhető beágyazási domaint használj.
Nem töltődik be az iframe vagy szkript	Ellenőrizd a CMS szkriptkorlátozásait és a Content Security Policy beállításait.
Más ügyfél vagy előfizetés látszik	Ellenőrizd a szerveroldali összerendelést és az egyedi előfizetés-azonosítót.
A nyitva hagyott felület nem reagál	Töltsd újra az oldalt; a widget interakciós munkamenete időkorlátos.
`429` válasz	Csökkentsd az újratöltéseket és kéréseket, majd próbáld később. A betöltő és a megjelenítő végpont kéréskorlátos.

Kapcsolódó útmutatók: Widgetek beállításai, REST API-integráció, webhookok.