Przejdź do głównej zawartości
Saiku Cloud

Pluginy (zaawansowane)

Plugin kafelka to najpotężniejszy własny kafelek: samowystarczalny widget HTML + JavaScript, który rysuje się wewnątrz zamkniętego iframe’a w piaskownicy, podczas gdy Saiku podaje mu wiersze zapytania kafelka. Użyj go, gdy ani kafelki wbudowane, ani deklaratywne własne renderery nie potrafią narysować tego, czego potrzebujesz — wskaźnika szytego na miarę, nietypowego układu, widgetu zrobionego pod konkretny cel.

Pluginy to funkcja zaawansowana, kontrolowana przez administratora. Ta strona jest głównie o ich modelu zaufania, bo trafić w to jest ważniejsze niż mechanika.

Jak instaluje się plugin

Operator (nie użytkownik dashboardów) wrzuca bundle do katalogu na serwerze Saiku:

${saiku.home}/tile-plugins/
  records-bars/
    plugin.json    # id, label, and an optional option schema
    plugin.html    # self-contained widget: inline CSS/JS, data: images only
  • plugin.json deklaruje id plugina (slug w rodzaju records-bars), wyświetlaną label oraz opcjonalnie optionSchema opisujący opcje konfigurowalne przez autora.
  • plugin.html to sam widget — pojedynczy, samowystarczalny dokument HTML z CSS-em i JavaScriptem inline (żadnych zdalnych skryptów, styli ani fontów; obrazy muszą być URI data:).

Serwer skanuje katalog i udostępnia zainstalowane pluginy do wyboru. Autor dashboardu dodaje jeden z + Dodaj kafelek, gdzie każdy zainstalowany plugin pojawia się jako osobna pozycja; utrwalony kafelek przechowuje wyłącznie id plugina, nigdy znaczników.

Saiku dostarcza jeden przykład zalążkowy — records-bars, prosty wykres słupkowy rekordów — żeby świeża instalacja miała działający plugin do obejrzenia i skopiowania.

Co piaskownica powstrzymuje, a czego nie

Każda ramka plugina działa za dwiema warstwami ograniczeń.

1. iframe sandbox="allow-scripts" (celowo bez allow-same-origin). Ramka działa w nieprzejrzystym originie null, więc kod plugina nie może:

  • czytać DOM-u, ciasteczek ani localStorage strony nadrzędnej;
  • widzieć sesji Saiku, tokenu osadzania ani danych z innego originu;
  • otwierać popupów, wysyłać formularzy, nawigować górnym oknem ani wyzwalać pobrań.

2. Restrykcyjna Content-Security-Policy na ramce (default-src 'none', brak connect-src). To blokuje wyjście sieciowe w tle — fetch, XHR, WebSocket, EventSource, sendBeacon, zdalne podzasoby oraz klasyczny beacon <img src="https://evil…">.

Zamykanie kanału samonawigacji

Jeśli chcesz zamknąć także kanał wyprowadzania danych przez samonawigację, operator ustawia restrykcyjny frame-src w CSP wdrożenia przez saiku.security.csp (na reverse proxy albo w konfiguracji CSP launchera). Ograniczenie tego, dokąd ramki pluginów mogą nawigować, to jedyny sposób rządzenia nawigacją — piaskownica per kafelek i CSP z założenia tego nie potrafią.

Protokół między pluginem a hostem

Host i plugin porozumiewają się wyłącznie przez window.postMessage. Przy montowaniu host wstrzykuje kryptograficzny nonce dla każdej ramki; każda wiadomość wysłana przez plugin musi odbić ten nonce, inaczej zostaje odrzucona (origin ramki w piaskownicy to napis "null", więc nonce jest jedynym godnym zaufania uwierzytelniaczem).

  • Host → plugin: init (opcje autora), data (rekordy zapytania), theme i resize.
  • Plugin → host: ready (załadowałem się), resize (ustaw proszę moją wysokość — przycinane przez hosta), filter (zaznaczenie, które host rozwiązuje na nowo wobec żywej kostki — plugin nie wstrzyknie MDX-a) oraz error (renderowane wyłącznie jako czysty tekst).

Host waliduje i przycina wszystko, co plugin wysyła; wiadomość zniekształcona albo nieuwierzytelniona jest ignorowana, a nie wykonywana.

Pluginy w osadzonych Appkach

Gdy Appka jest osadzona, jej kafelki pluginów są serwowane w zakresie tokenu: gość może załadować dokładnie te pluginy, do których odwołują się kafelki osadzonej Appki, i nic więcej. Obowiązuje to samo ograniczenie piaskownicą i CSP, i ta sama uwaga o samonawigacji — więc powyższa wskazówka o frame-src jest kontrolą operatora także dla osadzonych Appek.

Powiązane