MainWP Abilities

A bővítmény tizenkét képességet (ability) regisztrál a mainwp-matomo kategóriában, mindegyik a mainwp/ névtérben a MainWP Dashboardon. Segítségükkel kapcsolati állapotot olvashatsz, tulajdonokat listázhatsz, hozzárendeléseket nézhetsz meg és módosíthatsz, elemzési pillanatképeket és trendeket olvashatsz, valamint háttérfrissítést kérhetsz, ellenőrizhetsz vagy leállíthatsz. A frissítési kéréseket a WordPress ütemezett feladatai dolgozzák fel. Az elfogadott kérés csak annyit jelent, hogy sorba került, a végrehajtást az operáció állapotából ellenőrizheted.

Követelmények

• WordPress 6.9 vagy újabb, és Abilities API-t támogató MainWP Dashboard (a lenti input_json példákhoz MainWP Dashboard 6.2 vagy újabb).
• Aktív Matomo-bővítmény a MainWP Dashboardon.
• Hitelesített felhasználó manage_options joggal és hozzáféréssel a Matomo-kiegészítőhöz.
• Webhelyspecifikus hívásokhoz hozzáférési és szerkesztési jog a webhelyhez, és csatlakoztatott MainWP-webhely.
• Működő WordPress ütemezettfeladat-futtató a frissítési kérésekhez.
• Frissítés után egy rendszergazdának meg kell nyitnia a wp-admin felületet, hogy lefusson az átállás (lásd: Frissítés, törlés és eltávolítás).

A hitelesítéshez használhatsz alkalmazásjelszót (Application Password) vagy a MainWP Abilities API többi hitelesítési módját. A példák alkalmazásjelszót használnak. A Team Control korlátozásai az olvasásra és az írásra is vonatkoznak. A webhelyspecifikus olvasáshoz a kiválasztott webhely szerkesztési joga is kell. Az operáció állapotát és a leállítást csak az a felhasználó éri el, aki kérte. A jelentések külön olvasási útja (lásd: Webhelyek, adatok és jelentések) ezekre a képességekre nem vonatkozik.

A képességek

Képesség	Módszer	Cél
mainwp/get-matomo-connection-v1	GET	A kapcsolat és az elemzési szabályzat kitakart olvasása
mainwp/replace-matomo-connection-v1	POST	A kapcsolat és a beállítások előnézete vagy cseréje
mainwp/list-matomo-properties-v1	GET	Tulajdonok listázása a gyorsítótárból
mainwp/get-site-matomo-assignment-v1	GET	Egy webhely hozzárendelésének és revíziójának olvasása
mainwp/preview-site-matomo-assignment-v1	GET	Hozzárendelés-módosítás előnézete, előnézeti token kérése
mainwp/replace-site-matomo-assignment-v1	POST	Az előnézett hozzárendelés alkalmazása vagy újraellenőrzése
mainwp/get-site-matomo-observation-v1	GET	A gyorsítótárazott aktuális és előző elemzési pillanatkép olvasása
mainwp/get-site-matomo-trend-v1	GET	Napi adatsor olvasása egy adott pillanatképből
mainwp/request-matomo-property-refresh-v1	POST	A tulajdonlista frissítésének sorba állítása
mainwp/request-site-matomo-refresh-v1	POST	Egy webhely elemzési adatainak frissítése egy időszakra
mainwp/get-matomo-operation-v1	GET	Saját frissítési operáció állapotának olvasása
mainwp/cancel-matomo-operation-v1	POST	Leállítás előnézete vagy kérése

A teljes bemeneti és kimeneti sémát így kérheted le:

curl -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities?category=mainwp-matomo'

Az író képességek „destruktív” és „idempotens” jelölést kapnak. A bővítmény támogatja a JSON POST kéréseket (ahogy itt is látod), és a WordPress által a destruktív képességekhez választott natív DELETE módszert is. Mindkettő ugyanazt a /run végpontot és a {"input":{...}} JSON-törzset használja.

Kérési szabályok

Minden bemenet elutasítja a felesleges tulajdonságokat. A dry_run és a confirm JSON logikai érték legyen.

Mód	dry_run	confirm	Hatás
Előnézet	true	false vagy elhagyva	A kérést ellenőrzi, de nem menti a változtatást és nem állít sorba frissítést
Végrehajtás	false vagy elhagyva	true	Alkalmazza a változtatást vagy elfogadja a frissítési kérést

Ha mindkét jelző true, a kérés érvénytelen. Ha mindkettőt elhagyod vagy mindkettő false, a válasz mainwp_matomo_confirmation_required.

• A webhelyet a site_id_or_domain mező adja meg, például 1, "1" vagy "example.com". Pontos MainWP-azonosító vagy domain kell. A számazonosító pozitív egész legyen: a nulla, a vezető nullák, a tizedes törtek és a szóközök érvénytelenek.
• Az account_ref, catalog_ref, property_ref, snapshot_ref és a revíziók átláthatatlan, 64 karakteres, kisbetűs hexadecimális értékek, amelyeket a képességek adnak vissza. Ne állítsd össze őket magad. A Matomo számazonosítója nem helyettesíti a property_ref értéket.
• Minden íráshoz UUID formátumú request_ref kell. Csak ugyanazon felhasználó azonos kérésének megismétlésekor használd újra, más kéréshez új UUID kell.
• A hozzárendelés előnézeti tokenjének és az if_match revíziónak ugyanarra a webhelyre és ugyanarra a javasolt tulajdonra kell vonatkoznia.

Kapcsolat olvasása

Képesség: mainwp/get-matomo-connection-v1, módszer: GET, bemenet nincs.

curl -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-matomo-connection-v1/run'

Válaszmező	Jelentés
connection_state	missing, configured, invalid vagy migration_required
account_ref	Az aktuális fiókgeneráció, vagy null
origin_class	public_https, private_allowlisted vagy unset
range_days	Az alapértelmezett, bezárólag számolt jelentési időszak, 1 és 366 nap között
refresh_hours	A frissítés időköze, 1 és 720 óra között
revision	Az aktuális kapcsolati revízió az if_match mezőhöz

A válasz nem tartalmazza az URL-t és az API-tokent. A kapcsolat módosítása előtt olvasd el.

Kapcsolat előnézete vagy cseréje

Képesség: mainwp/replace-matomo-connection-v1, módszer: POST.

Bemenet	Kötelező	Jelentés
origin_url	igen	A Matomo abszolút HTTPS alap URL-je, almappával, ha van, például https://analytics.example.com vagy https://example.com/matomo/
api_token	igen	Új, csak írható token, vagy JSON null a mentett token megtartásához
trust_profile	igen	public, vagy private_allowlisted a kiszolgálói szabályzat által kifejezetten engedélyezett címhez
timeout_seconds	igen	1 és 30 közötti egész
range_days	igen	1 és 366 közötti egész
refresh_hours	igen	1 és 720 közötti egész
if_match	igen	Az aktuális kapcsolati revision
request_ref	igen	A kérést azonosító UUID
dry_run, confirm	a kérési szabályok szerint	Előnézet vagy végrehajtás

Az URL-re ugyanazok a szabályok vonatkoznak, mint a beállítóoldalon (lásd: Kapcsolat beállítása). A tanúsítványellenőrzés mindig be van kapcsolva. A private_allowlisted előfeltétele egy már meglévő kiszolgálóoldali engedélylista, a kiválasztása önmagában nem ad hozzáférést privát célhoz.

Az api_token: null csak akkor használható, ha ugyanazt a kiszolgálót, portot, almappát és bizalmi profilt tartod meg, és van használható mentett token. Bármelyik módosításához token kell. Az azonos kiszolgáló másik almappája külön telepítés. A tokent a válasz sosem adja vissza.

Kezdd dry_run: true móddal. Az előnézet is felveszi a kapcsolatot a Matomóval, ezért elérhető kiszolgáló és érvényes token kell hozzá. A megerősített kérés előtt nézd meg a changed, credential_action (retained vagy rotated), property_count és rebind_count értékeket.

Az eredet, a token vagy a bizalmi profil módosítása új fiókgenerációt hoz létre: a meglévő hozzárendeléseket újra kell kötni, a régi helyi hozzárendelések és gyorsítótárazott adatok törlődnek, az előző fiók még el nem indított operációi leállnak. A rebind_count az érintett hozzárendelések számát adja.

A teljesült válasz a mode, request_id, changed, credential_action, property_count, rebind_count és az új revision mezőt tartalmazza. A megerősített híváshoz az előnézetnél használt aktuális revíziót add meg, az előnézet nem menti a javasolt revíziót.

Tulajdonok listázása

Képesség: mainwp/list-matomo-properties-v1, módszer: GET.

curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"limit":25}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/list-matomo-properties-v1/run'

Választható bemenet a limit (1 és 100 között, alapérték 25) és az after_property_ref (egy korábban kapott kurzor vagy null). A válasz tartalmazza a catalog_ref, a state (fresh vagy stale), a properties, a next_after_property_ref és a truncated mezőt. Minden tulajdonnak van property_ref, display_name és assignment_state (unassigned vagy assigned) értéke. Ha a truncated értéke true, a next_after_property_ref értékkel folytasd. A képesség a teljes, gyorsítótárazott listát olvassa, a Matomóból nem kér le tulajdonokat, ahhoz a tulajdonlista-frissítést használd.

Hozzárendelés olvasása, előnézete és cseréje

Hozzárendelés olvasása

Képesség: mainwp/get-site-matomo-assignment-v1, módszer: GET.

curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"site_id_or_domain":1}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-site-matomo-assignment-v1/run'

A válasz: site_id, assignment_state (unassigned, assigned vagy rebind_required), property_ref, property_name és revision. A revíziót tartsd meg az előnézethez. A kapcsolat módosítása újrakötést tehet szükségessé akkor is, ha a webhelynek volt korábbi hozzárendelése.

Javasolt hozzárendelés előnézete

Képesség: mainwp/preview-site-matomo-assignment-v1, módszer: GET. Kötelező bemenet: site_id_or_domain, property_ref és if_match. A property_ref értékét a gyorsítótárazott listából válaszd, vagy JSON null értékkel szüntesd meg a hozzárendelést. Az if_match a webhely aktuális hozzárendelési revíziója legyen.

A válasz: site_id, desired_state, would_change, cache_effect (none vagy mark_stale), conflict_state (none vagy property_already_assigned), preview_token és expires_at. Egy tulajdon csak egy MainWP-webhelyhez tartozhat, a property_already_assigned ütközést a módosítás előtt oldd fel. Az előnézeti token öt percig érvényes, és a kérő felhasználóhoz, a webhelyhez, a fiókhoz, a listához, a tulajdonhoz és a hozzárendelési revízióhoz kötött. Ha ezek bármelyike változik, olvasd el az aktuális állapotot, és kérj új előnézetet.

Hozzárendelés cseréje

Képesség: mainwp/replace-site-matomo-assignment-v1, módszer: POST. Kötelező bemenet: site_id_or_domain, property_ref, if_match, preview_token és request_ref, valamint a kívánt módhoz tartozó jelzők. Pontosan az előnézet értékeit add meg. A próbafuttatás újraellenőrzi az előnézetet, a megerősített hívás menti a hozzárendelést, és ha az megváltozott, érvényteleníti a korábbi elemzési adatokat.

A válasz: mode (preview vagy completed), request_id, site_id, assignment_state, changed és az új revision. A hozzárendelés módosítása után kérj webhelyfrissítést, hogy az új tulajdon adatai betöltődjenek.

Elemzési pillanatképek és trendek

Pillanatkép olvasása

Képesség: mainwp/get-site-matomo-observation-v1, módszer: GET. Kötelező bemenet: site_id_or_domain. A választható snapshot_ref pontos pillanatképet jelöl ki, elhagyva vagy null értékkel az aktuális időszak legfrissebbjét kapod.

curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"site_id_or_domain":1}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-site-matomo-observation-v1/run'

A válasz: site_id, snapshot_ref, state, start_date, end_date, observed_at, current és previous. Mindkét időszak tartalmazza:

Mező	Jelentés
visits	Látogatások száma
unique_visitors	Egyedi látogatók száma, vagy null, ha nem elérhető
users	Felhasználók száma, vagy null, ha nem elérhető
actions	Műveletek száma
average_engagement_seconds	Átlagos elköteleződési idő másodpercben
bounce_rate	Százalék 0 és 100 között

A régi (stale) pillanatkép frissítésre szoruló, gyorsítótárazott adat. A hiányzó pillanatkép mainwp_matomo_snapshot_not_found hibát ad: előbb kérj webhelyfrissítést. Ezek az olvasások nem indítanak élő Matomo-kérést.

Napi trend olvasása

Képesség: mainwp/get-site-matomo-trend-v1, módszer: GET. Kötelező bemenet: site_id_or_domain, a pillanatképből kapott snapshot_ref és a metric. A támogatott mutatók: visits, unique_visitors, users és actions. A válasz: site_id, snapshot_ref, metric, timezone és a napi points. Minden ponthoz tartozik date és value, a nem elérhető mutató értéke null lehet. Legfeljebb 366 pont jön. Ugyanazt a pillanatkép-hivatkozást használd, hogy az összegzés és a trend egyező legyen.

Ütemezett frissítések kérése

A frissítési kérések azelőtt válaszolnak, hogy a szolgáltatói munka befejeződne. A tartós sort a WordPress ütemezett feladatai dolgozzák fel. Az aktuális Matomo-fiókhoz egyszerre csak egy frissítés lehet aktív, másik kérés mainwp_matomo_lock_busy hibát adhat.

Tulajdonlista frissítése

Képesség: mainwp/request-matomo-property-refresh-v1, módszer: POST. Küldd a request_ref mezőt és a mód jelzőit. A megerősített kérés a teljes tulajdonlistát frissíti.

curl -X POST -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"request_ref":"9e38a2d1-52ec-4ef0-bfe8-795f01c4b7d0","confirm":true}}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/request-matomo-property-refresh-v1/run'

A válasz: mode (preview vagy accepted), operation_id, status, account_ref és accepted_at. Az előnézet nem hoz létre operációt, és az elfogadás ideje null.

Webhelyadatok frissítése

Képesség: mainwp/request-site-matomo-refresh-v1, módszer: POST. Kötelező bemenet: site_id_or_domain, start_date, end_date és request_ref, valamint a mód jelzői. A dátumok ÉÉÉÉ-HH-NN alakúak, a bezárólag számolt időszak 1 és 366 nap közötti, és a kezdet nem lehet a végnél későbbi. A webhelynek érvényes hozzárendeléssel kell rendelkeznie.

curl -X POST -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"site_id_or_domain":1,"start_date":"2026-10-01","end_date":"2026-10-07","request_ref":"053ac987-41b3-49b1-8c71-356f809fe4ac","confirm":true}}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/request-site-matomo-refresh-v1/run'

A válasz: mode, operation_id, site_id, status, range_days és accepted_at. Az operáció az aktuális fiókhoz, a kapcsolati revízióhoz, a hozzárendeléshez és a webhely azonosságához kötött, ezek változása megakadályozhatja a futását. Mindkét frissítésnél az operation_id a kérés UUID-ja. Ugyanezzel az UUID-dal megismételt, azonos kérés a meglévő operációt adja vissza, amíg az elérhető. A kérés vagy a hozzá kötött állapot módosítása mainwp_matomo_request_conflict hibát adhat.

Operáció ellenőrzése és leállítása

Állapot lekérése

Képesség: mainwp/get-matomo-operation-v1, módszer: GET. Kötelező bemenet: operation_ref.

curl -G -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  --data-urlencode 'input_json={"operation_ref":"053ac987-41b3-49b1-8c71-356f809fe4ac"}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/get-matomo-operation-v1/run'

A válasz: operation_id, kind (property_refresh vagy site_refresh), site_id (tulajdonlista-frissítésnél null), status, retryable, error_code, accepted_at és finished_at.

Állapot	Jelentés
queued	Elfogadva, ütemezett feldolgozásra vár
running	A feldolgozás elindult
succeeded	A frissítés befejeződött
failed	A frissítés meghiúsult, nézd meg az error_code és a retryable értékét
unknown	Az eredmény nem állapítható meg, nézd meg az aktuális adatokat, és egyeztesd, mielőtt újabb frissítést kérsz
cancel_requested	A leállítás biztonságos hívási határra vár
cancelled	Az operáció leállt
skipped_access_lost	A szükséges hozzáférés elveszett a befejezés előtt

Az állapotlekérés nem indítja el a sorban álló munkát. Ha egy operáció sokáig queued marad, ellenőrizd a Dashboard webhely WordPress ütemezettfeladat-futtatóját. Az operációs bejegyzéseket 30 napig őrzi a rendszer, kivéve ha a webhely törlése vagy a bővítmény eltávolítása előbb letörli őket.

Operáció leállítása

Képesség: mainwp/cancel-matomo-operation-v1, módszer: POST. Kötelező bemenet: operation_ref, a leállításhoz külön UUID request_ref, és a mód jelzői.

curl -X POST -u 'FELHASZNALO:ALKALMAZASJELSZO' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"operation_ref":"053ac987-41b3-49b1-8c71-356f809fe4ac","request_ref":"649b8f4d-1778-489c-9194-74306793bfd4","confirm":true}}' \
  'https://a-dashboard-cimed.hu/wp-json/wp-abilities/v1/abilities/mainwp/cancel-matomo-operation-v1/run'

A válasz: mode, request_id, operation_id, previous_status, status és quiescence. A sorban álló operáció cancelled lesz quiescence: before_dispatch értékkel. A futó operáció cancel_requested lesz quiescence: at_call_boundary értékkel. A leállítás együttműködő: nem szakítja meg azonnal a már úton lévő Matomo-kérést, és nem vonja vissza a kész munkát. Ellenőrizd az állapotot, amíg végállapotba nem kerül. Befejezett operáció leállítása mainwp_matomo_cancel_conflict hibát ad.

Hibák és újrapróbálás

Hibakód	HTTP-állapot	Teendő
mainwp_matomo_authentication_required	401	Ellenőrizd a hitelesítést
mainwp_matomo_access_denied	403	Ellenőrizd a Dashboard-, Matomo-, webhely- és szerkesztési jogokat
mainwp_matomo_invalid_input	400	Ellenőrizd a kötelező mezőket, típusokat, dátumokat, URL-korlátozásokat és a felesleges tulajdonságokat
mainwp_matomo_confirmation_required	409	Válassz előnézeti vagy végrehajtási módot
mainwp_matomo_stale_revision	409	Olvasd el az aktuális beállítást vagy hozzárendelést, és nézd át újra a változtatást
mainwp_matomo_stale_preview	409	Kérj új hozzárendelési előnézetet
mainwp_matomo_property_conflict	409	Válassz olyan tulajdont, amely nincs másik webhelyhez rendelve
mainwp_matomo_request_conflict	409	Egyeztesd a korábbi kérést, másik szándékhoz használj új UUID-t
mainwp_matomo_lock_busy	409	Várd meg az aktív operációt vagy a konfigurációs zárat, tartsd be a retry_after értéket, ha van
mainwp_matomo_assignment_required	422	Előbb rendeld hozzá vagy kösd újra a webhelyet
mainwp_matomo_snapshot_not_found	404	Frissítsd a webhelyet, vagy ellenőrizd a pillanatkép-hivatkozást
mainwp_matomo_operation_not_found	404	Ellenőrizd a hivatkozást, a kérő felhasználót, a fiókot és a megőrzési időt
mainwp_matomo_cancel_conflict	409	Olvasd újra az állapotot, csak sorban álló vagy futó munka állítható le
mainwp_matomo_write_failed	500	Nézd meg az aktuális állapotot, és oldd meg a tárolási hibát
mainwp_matomo_storage_unavailable	503	Fejezd be az átállást, és oldd meg az adatbázis- vagy tárolási értesítéseket
mainwp_matomo_provider_unavailable	502	Ellenőrizd a Matomo elérhetőségét, a hitelesítő adatokat és a TLS-beállítást
mainwp_matomo_outcome_unknown	502	Egyeztesd az aktuális kapcsolati, hozzárendelési vagy operációs állapotot az újrapróbálás előtt

A hibák tartalmazhatnak retryable és retry_after mezőt. Az időtúllépés vagy a bizonytalan válasz nem bizonyítja, hogy semmi nem változott. Előbb olvasd el a vonatkozó aktuális állapotot vagy operációt, azonos újrapróbálásnál tartsd meg az UUID-t, és ne küldj más kérést, amíg a korábbi eredmény nem világos.