# Fogyasztó Barát Shopify App - Admin és ügyfélszolgálati dokumentáció

Ez a dokumentáció a Fogyasztó Barát oldali admin és ügyfélszolgálati kollégáknak szól. A célja az, hogy átláthatóan bemutassa, mit tud az app, melyik beállítás mire való, milyen tipikus hibák fordulhatnak elő, és mikor érdemes azonnal fejlesztői segítséget kérni.

Ez az anyag nem fejlesztői szemmel magyarázza a rendszert, hanem működési oldalról. A hangsúly azon van, hogy a kolléga gyorsan megértse, mi történik az appban, mit kell ellenőrizni egy adott merchantnál, és mikor milyen magyarázatot érdemes adni.

## Tartalomjegyzék
1. [Az app célja](#1-az-app-celja)
2. [Mit tud az app röviden](#2-mit-tud-az-app-roviden)
3. [A beállítási felület felépítése](#3-a-beallitasi-felulet-felepitese)
4. [Fogyasztó Barát widget](#4-fogyaszto-barat-widget)
5. [Értékelések a köszönő oldalon](#5-ertekelesek-a-koszono-oldalon)
6. [ÁSZF és adatkezelési oldalak](#6-aszf-es-adatkezelesi-oldalak)
7. [Checkout alján linkelt szabályzat (policy) felugró ablakok](#7-checkout-aljan-linkelt-szabalyzat-policy-felugro-ablakok)
8. [PDF csatolmányok a rendelés-visszaigazoló emailhez](#8-pdf-csatolmanyok-a-rendeles-visszaigazolo-emailhez)
9. [Automatikus távoli szabályzat (policy) frissítés](#9-automatikus-tavoli-szabalyzat-policy-frissites)
10. [Ajánlott ügyfélkezelési helyzetek](#10-ajanlott-ugyfelkezelesi-helyzetek)
11. [Tipikus hibák és teendők](#11-tipikus-hibak-es-teendok)
12. [Mikor kell fejlesztő bevonása](#12-mikor-kell-fejleszto-bevonasa)

## 1. Az app célja

Az app a Shopify bolt és a Fogyasztó Barát rendszer összekötését végzi. Ennek három jól elkülöníthető eredménye van. Az első, hogy a Fogyasztó Barát widget megjelenhet a boltban. A második, hogy a köszönő oldalon elérhetővé válik az értékelés. A harmadik, hogy az ÁSZF és adatkezelési tartalmak egyrészt normál Shopify oldalakon, másrészt a checkout alján linkelt szabályzat (policy) felugró ablakokban is kezelhetők.

Ügyfélszolgálati szempontból fontos különbség, hogy ez a három terület nem ugyanúgy működik. Másképp kell kezelni a storefronton megjelenő widgetet, másképp a köszönő oldali értékelést, és megint másképp a Shopify saját jogi popupjait.

## 2. Mit tud az app röviden

Az app a gyakorlatban az alábbi feladatokat tudja ellátni:

- kezeli a `Widget ID` megadását
- ellenőrzi az előfizetés állapotát
- engedélyezi a Fogyasztó Barát widgetet
- engedélyezi a köszönő oldali értékelést
- lehetővé teszi az ÁSZF és adatkezelési oldal kiválasztását
- beilleszti az adott oldalba a Fogyasztó Barát Multifunkciós kódját
- frissíti a Shopify checkout alján linkelt ÁSZF és adatkezelési popup tartalmakat
- útmutatást ad a rendelés-visszaigazoló email PDF csatolmányának beállításához
- képes távoli, szerver-szerver szabályzat (policy) frissítésre is

## 3. A beállítási felület felépítése

Az admin felület blokkos szerkezetű, és ez nem csak dizájnkérdés. Minden blokk külön funkciócsoportot fed le.

Felül látható a bolt publikus domainje és a Fogyasztó Barát azonosítóhoz kapcsolódó állapot. Ez alatt külön blokkokban szerepel a Fogyasztó Barát widget, az értékelések, az ÁSZF oldal, az adatkezelési oldal, majd külön a checkout popup szabályzat (policy) frissítő részek. Legalul egy információs blokk található a rendelés-visszaigazoló email PDF csatolmányához kapcsolódó teendőkről.

Ez a felosztás azért fontos, mert a merchantok gyakran összekeverik az oldalas megjelenítést a checkout popupokkal. Az ügyfélszolgálati kommunikációban érdemes mindig külön kimondani, hogy most normál Shopify oldalról vagy checkout popup szabályzatról van szó.

## 4. Fogyasztó Barát widget

A Fogyasztó Barát widget működéséhez több feltételnek együtt kell teljesülnie. A merchantnak meg kell adnia a `Widget ID`-t, az előfizetésnek aktívnak kell lennie, és az appban is engedélyezni kell a widgetet. Ez azonban még mindig nem elég a tényleges megjelenéshez, mert a Shopify Theme Editorban az app embedet is külön be kell kapcsolni.

Ez az egyik leggyakoribb félreértési pont. Ha a merchant azt mondja, hogy a widget “be van kapcsolva, mégsem látszik”, akkor elsőként nem hibaként kell kezelni, hanem végig kell ellenőrizni ezt a négy feltételt. Tapasztalat szerint sokszor a Theme Editorban marad el az utolsó lépés.

## 5. Értékelések a köszönő oldalon

Az értékelések résznél hasonló a helyzet, de fontos Shopify korlátokkal. A köszönő oldalon nem lehet a klasszikus Fogyasztó Barát widgetet ugyanabban a formában megjeleníteni, mint a storefronton. Itt egy külön checkout extension blokk jelenik meg, amely a vásárlót az értékelő oldalra vezeti.

Ez azt jelenti, hogy ha a merchant teljes widgetélményt vár a köszönő oldalon, azt már az elején érdemes tisztázni. A működő megoldás itt egy Shopify-kompatibilis blokk, nem ugyanaz a megjelenítés, mint a normál boltoldalakon.

Ahhoz, hogy az értékelés működjön, az appban engedélyezni kell a funkciót, és a Shopify checkout editorban a megfelelő blokkot is hozzá kell adni.

## 6. ÁSZF és adatkezelési oldalak

Az ÁSZF és adatkezelési résznél a merchant egy normál Shopify oldalt választ ki, amelybe az app beilleszti a Fogyasztó Barát Multifunkciós kódját. Ez a megoldás arra szolgál, hogy a jogi tartalom külön, publikus oldalon is elérhető legyen.

Amikor a merchant bekapcsolja az oldali scriptet, az app a kiválasztott oldal tartalmába beilleszti a saját markerelt blokkot. Ha a kapcsolót később kikapcsolja, az app ezt a saját részt el is tudja távolítani. Ez fontos, mert a merchant saját egyéb tartalmát nem írjuk felül feleslegesen.

Ügyfélszolgálati oldalról itt azt kell figyelni, hogy valóban a megfelelő Shopify oldal lett-e kiválasztva, és a merchant tényleg létrehozta-e ezt az oldalt. Sokszor nem technikai hiba van, hanem egyszerűen nincs még külön ÁSZF vagy adatkezelési oldal.

## 7. Checkout alján linkelt szabályzat (policy) felugró ablakok

Ez a rész külön kezelendő az oldalas megoldástól. A checkout alján linkelt jogi tartalmak a Shopify saját szabályzat (policy) popupjai. Ezek nem ugyanazok, mint a normál Shopify oldalak.

Az ÁSZF frissítő gomb a Shopify Szolgáltatási feltételek popup tartalmát frissíti, és ezzel együtt a visszaküldési vagy refund szabályzat (policy) tartalmát is. Az adatkezelési gomb a Shopify Adatvédelmi szabályzat popup tartalmát frissíti.

Az adatkezelésnél van egy fontos működési korlát. Ha a Shopifyban az adatvédelmi szabályzat automatizált kezelés alatt áll, az app nem tud beleírni. Ilyenkor a merchantnak a Shopify adminban ki kell kapcsolnia ezt az automatizálást. Ezt a felület külön figyelmeztetéssel jelzi.

## 8. PDF csatolmányok a rendelés-visszaigazoló emailhez

Az app nem szerkeszti automatikusan a rendelés-visszaigazoló email sablont. Ehelyett tájékoztatást ad arról, hogy a merchantnak milyen Liquid snippetet kell kézzel beillesztenie a megfelelő Shopify értesítési sablonba.

Itt fontos megérteni az összefüggést: a Shopify a szabályzat (policy) tartalmából készít PDF-et. Emiatt az ÁSZF popup frissítése nem csak a checkout popup miatt fontos, hanem az email csatolmány szempontjából is. Ha a szabályzat tartalma elavult, a PDF is elavult lesz.

## 9. Automatikus távoli szabályzat (policy) frissítés

Az app támogat egy külső, szerver-szerver alapú szabályzat (policy) refresh folyamatot is. Ennek az a célja, hogy a Fogyasztó Barát rendszer jogszabályváltozás esetén úgy tudjon Shopify szabályzatot frissíteni, hogy a merchantnak ne kelljen külön belépnie és gombot nyomnia.

Ez a működés hitelesített requestre épül. A kérés tartalmazza a `shop_url`, `widget_id`, `action` és `timestamp` mezőket, valamint egy aláírást. Ügyfélszolgálati szinten nem az a fontos, hogy a pontos HMAC hogyan működik, hanem az, hogy ez nem nyitott endpoint, és nem tetszőleges külső kérés futtatja.

Fontos működési részlet, hogy a Fogyasztó Barát oldali közzététel és a tömeges dokumentumgenerálás is automatikusan el tudja indítani ezt a Shopify frissítést.

Ez két Fogyasztó Barát oldali folyamatból történik:

- `ajax/public.php` közzétételkor
- `pages/generate-all-docs-ajax.php` tömeges generáláskor

Gyakorlatban ez azt jelenti, hogy ha egy Shopify shopnál telepítve van az app, és mentve van a megfelelő Widget ID, akkor a Fogyasztó Barát oldalon frissített dokumentumtípus a Shopify appban is automatikusan frissülhet. Emiatt nem minden esetben kell a merchantnak külön belépnie a Shopify appba és kézzel megnyomnia a frissítő gombokat.

## 10. Ajánlott ügyfélkezelési helyzetek

### 10.1. Új merchant beállítása

Egy új merchantnál a legjobb sorrend az, ha először a `Widget ID` és az előfizetés kerül ellenőrzésre. Ezután jöhet a Fogyasztó Barát widget bekapcsolása, majd a Theme Editor ellenőrzése. Ezután érdemes bekapcsolni az értékelést, ellenőrizni a checkout editor blokkot, végül kiválasztani az ÁSZF és adatkezelési oldalakat, és szükség esetén lefuttatni a popup szabályzat (policy) frissítést.

### 10.2. Merchant szerint minden be van állítva, mégsem működik

Ilyenkor érdemes lépésenként haladni. Előbb mindig azt kell tisztázni, hogy pontosan melyik funkció nem működik. Más a teendő, ha a storefronton nem látszik a widget, más, ha a köszönő oldali értékelés hiányzik, és megint más, ha az ÁSZF popup tartalma nem a várt. A legtöbb hiba abból adódik, hogy a merchant két külön működési területet egynek lát.

### 10.3. Jogszabályváltozás utáni ellenőrzés

Jogszabályváltozás esetén érdemes külön ellenőrizni az oldalas tartalmakat és a checkout popupokat. Az is fontos, hogy a rendelés-visszaigazoló email PDF csatolmány szempontjából a megfelelő szabályzat (policy) tartalom valóban frissült-e.

## 11. Tipikus hibák és teendők

### 11.1. Nincs aktív előfizetés

Ha a merchantnál nincs aktív előfizetés, a widget és az értékelés működése korlátozott lehet. Ilyenkor a `Widget ID` és az előfizetés állapotát kell ellenőrizni.

### 11.2. A Fogyasztó Barát widget nem jelenik meg

Ilyenkor először azt kell megnézni, hogy a widget engedélyezve van-e az appban, és a Theme Editorban be van-e kapcsolva az app embed. Ez tipikusan nem backend hiba, hanem hiányos bekapcsolási folyamat.

### 11.3. A köszönő oldali értékelés nem jelenik meg

Ilyenkor a checkout editorban kell ellenőrizni, hogy a blokk valóban hozzá lett-e adva. Az app oldali bekapcsolás önmagában nem elegendő.

### 11.4. Az adatkezelési szabályzat (policy) nem frissül

Ez gyakran azért történik, mert a Shopify adatvédelmi szabályzata automatizált módon kezelt. Ilyenkor a merchantnak ezt a védelmet ki kell kapcsolnia, különben az app nem tud írni a szabályzatba.

### 11.5. A távoli refresh nem találja a shopot

Lehetséges, hogy hibás `shop_url` vagy hibás `widget_id` ment ki, de az is előfordulhat, hogy domainváltás után még nem szinkronizálódott az app oldali adat. Ez már gyakrabban igényel fejlesztői vizsgálatot.

### 11.6. PDF csatolmány hiányzik az emailből

Ilyenkor meg kell nézni, hogy a merchant ténylegesen beillesztette-e a szükséges Liquid snippetet az értesítési sablonba, és hogy a megfelelő szabályzat (policy) tartalom nem üres-e.

## 12. Mikor kell fejlesztő bevonása

Fejlesztői bevonásra akkor van szükség, ha az app szerver oldali hibát ad, a távoli refresh endpoint 500-as válasszal tér vissza, a szabályzat (policy) tartalom nem frissül annak ellenére, hogy a request látszólag helyes, vagy ha domainváltás utáni lookup problémára gyanakszunk.

Szintén fejlesztői terület, ha új Shopify scope, adatbázis migráció vagy extension build és deploy kérdés merül fel. Ügyfélszolgálati oldalról itt a legfontosabb, hogy minél pontosabban legyen megfogalmazva, melyik funkció hibázik, milyen állapotok látszanak az adminban, és mit tapasztal a merchant a storefronton vagy a checkoutban.