Spis treści
1. Wtyczki w Livespace
Wtyczka osadza zewnętrzną aplikację webową jako widget <iframe> wewnątrz profilu w Livespace — szansy sprzedaży, firmy, osoby lub przestrzeni. Widget otrzymuje dane bieżącego rekordu oraz, gdy jest to potrzebne, tymczasowe dane dostępowe do API Livespace, przekazywane przez przeglądarkowe postMessage API.
Ta dokumentacja jest przeznaczona dla developerów tworzących lub konfigurujących osadzaną aplikację.
Jak to działa
Administrator konta rejestruje wtyczkę, podając nazwę i adres URL w protokole HTTPS, a następnie konfiguruje, które profile ją wyświetlają, w którym miejscu, jaki ma rozmiar oraz kto może ją zobaczyć.
Gdy użytkownik otworzy obsługiwany profil, widget ładuje się w skonfigurowanej pozycji i otrzymuje dane bieżącego rekordu przez postMessage.
Twoja aplikacja reaguje na ten kontekst i renderuje się odpowiednio.
Od czego zacząć
Bezpieczeństwo — HTTPS, lista dozwolonych domen, sandbox ramki iframe oraz walidacja origin, którym musi podlegać Twoja aplikacja.
Komunikaty kontekstowe — dane, które Livespace wysyła do widgetu, oraz sposób ich odbioru.
Dane dostępowe do API — opcjonalne tymczasowe dane dostępowe do wywoływania API Livespace.
Środowisko widgetu — rozmiary widgetu, umiejscowienie oraz wskazówki dotyczące projektowania responsywnego.
2. Bezpieczeństwo
Wtyczki uruchamiają kod firm trzecich wewnątrz interfejsu Livespace, dlatego każda wtyczka przechodzi przez kilka warstw zabezpieczeń — przed osadzeniem i w jego trakcie. Ta sekcja opisuje wymagania, którym musi sprostać Twoja aplikacja.
Wymóg HTTPS
Wszystkie adresy URL wtyczek muszą używać HTTPS. Zwykłe adresy HTTP są odrzucane podczas rejestracji.
Lista dozwolonych domen
Livespace utrzymuje listę zatwierdzonych domen (allowlist). Adres URL wtyczki zostaje zaakceptowany tylko wtedy, gdy jego domena znajduje się na tej liście.
Wtyczki hostowane na infrastrukturze Livespace są zatwierdzane automatycznie. Wtyczki hostowane na infrastrukturze zewnętrznej (dowolna domena nienależąca do Livespace) muszą przejść ręczny proces weryfikacji i zatwierdzenia, zanim będzie można je zarejestrować. Bez tego zatwierdzenia system odrzuca adres URL na etapie rejestracji.
Aby poprosić o zatwierdzenie zewnętrznej domeny, skontaktuj się ze wsparciem Livespace, podając:
domenę, na której zamierzasz hostować wtyczkę,
krótki opis aplikacji,
nazwę konta Livespace, w którym będzie używana.
Zatwierdzenie trwa zwykle kilka dni roboczych.
Ważne: Lista dozwolonych domen jest podstawową granicą bezpieczeństwa między Livespace a aplikacjami firm trzecich. Gwarantuje, że w kontach klientów można osadzić wyłącznie zweryfikowane, znane źródła.
Sandbox ramki iframe
Livespace osadza każdy plugin w sandbox HTML w postaci elementu iframe. Sandbox przyznaje stały zestaw uprawnień i blokuje wszystko poza nimi, dzięki czemu osadzona aplikacja nie może wykonywać wrażliwych operacji przeglądarki (takich jak nawigacja na poziomie strony nadrzędnej czy otwieranie okien modalnych), które mogłaby wykonać zwykła strona internetowa.
Poniższe uprawnienia są włączone. Każde uprawnienie, którego nie ma na liście, jest zablokowane.
Uprawnienie sandbox | Co pozwala zrobić Twojej aplikacji |
allow-scripts | Uruchamianie kodu JavaScript. |
allow-same-origin | Zachowanie własnego origin — odczyt i zapis własnych plików cookie oraz localStorage, a także wykonywanie żądań w obrębie tego samego origin. |
allow-forms | Wysyłanie formularzy HTML. |
allow-popups | Otwieranie nowych okien lub kart (na przykład window.open() lub linki z target="_blank"). |
allow-downloads | Wyzwalanie pobierania plików. |
Uwaga Ten zestaw uprawnień jest zarządzany przez Livespace i jest taki sam dla każdego pluginu. Nie można go konfigurować osobno dla poszczególnych pluginów. |
Walidacja origin
Livespace weryfikuje origin każdego komunikatu postMessage otrzymanego z ramki iframe wtyczki względem listy dozwolonych domen. Komunikaty z origin spoza listy są po cichu ignorowane.
Twoja wtyczka nie musi implementować własnej kontroli origin dla komunikatów wychodzących, ale musi zawsze walidować event.data.type w każdym przychodzącym komunikacie przed podjęciem działania. Zalecany, defensywny handler znajdziesz w sekcji Komunikaty kontekstowe poniżej.
3. Komunikaty kontekstowe
Gdy użytkownik otworzy obsługiwany profil z aktywną wtyczką, Livespace wysyła dane bieżącego rekordu do osadzonej ramki iframe za pomocą przeglądarkowego postMessage API. Komunikat jest wysyłany raz przy ładowaniu profilu oraz ponownie, jeśli użytkownik przejdzie do innego rekordu bez pełnego przeładowania strony.
Format komunikatu
{
type: 'livespace-plugin:context',
payload: {
deal?: { id: string /* UUID */, name: string },
company?: { id: string /* UUID */, name: string },
person?: { id: string /* UUID */, firstName: string, lastName: string },
space?: { id: string /* UUID */, name: string },
user: { id: string /* UUID */ }
}
}Typ profilu | Klucz payload | Pola |
Szansa sprzedaży | deal | id (UUID), name |
Firma | company | id (UUID), name |
Osoba | person | id (UUID), firstName, lastName |
Przestrzeń | space | id (UUID), name |
Wszystkie profile | user | id (UUID) — zawsze obecny |
Kluczowe zasady
Obecny jest dokładnie jeden klucz encji (deal, company, person lub space) — zależnie od profilu, który użytkownik aktualnie przegląda.
user.id jest obecny zawsze i stanowi jedyne pewne źródło tożsamości zalogowanego użytkownika.
Host może wysłać komunikat context ponownie, jeśli użytkownik przejdzie do innego rekordu. Traktuj każdy komunikat jako nowy stan i odpowiednio przerenderuj widok.
person używa pól firstName i lastName zamiast pojedynczego pola name.
Odbiór kontekstu w aplikacji
Nasłuchuj zdarzeń message na obiekcie window. Zawsze parsuj payload defensywnie i weryfikuj type przed podjęciem działania.
window.addEventListener('message', (event) => {
let data;
try {
data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
} catch (e) { return; }
if (!data || data.type !== 'livespace-plugin:context') return;
const { deal, company, person, space, user } = data.payload;
console.log('Current user ID:', user.id);
if (deal) {
console.log('Deal:', deal.id, deal.name);
// load deal-specific data
} else if (company) {
console.log('Company:', company.id, company.name);
} else if (person) {
console.log('Person:', person.id, person.firstName, person.lastName);
} else if (space) {
console.log('Space:', space.id, space.name);
}
});
4. Dane dostępowe do API
Jeśli wtyczka potrzebuje pobierać dane z API Livespace, może poprosić o tymczasowe dane dostępowe sesji przez postMessage. Jest to opcjonalne — wtyczki, które wyświetlają jedynie dane kontekstowe z komunikatu kontekstowego, nie potrzebują tego mechanizmu.
Żądanie danych dostępowych
Wyślij ten komunikat z ramki iframe do hosta:
{
"type": "livespace-plugin:request-api-credentials",
"payload": { "requestId": "<uuid-generated-per-request>" }
}Wygeneruj requestId za pomocą crypto.randomUUID().
Śledź oczekujące żądania w strukturze Map kluczowanej przez requestId, aby móc powiązać odpowiedzi.
Ustaw limit czasu na żądanie (10–15 s), który odrzuci Promise, jeśli odpowiedź nie nadejdzie — w przeciwnym razie brak odpowiedzi hosta zawiesi wtyczkę.
Odbiór danych dostępowych
Host odpowiada komunikatem:
{
"type": "livespace-plugin:api-credentials",
"payload": {
"requestId": "<echoed-from-request>",
"apiBaseUrl": "https://your-account.livespace.io",
"apiKey": "...",
"apiSha": "...",
"apiSession": "..."
}
}
Ważne: Przy obsłudze zwróconych danych dostępowych przestrzegaj poniższych zasad:
Zawsze wiąż odpowiedzi przez requestId. Odrzuć każdą odpowiedź, której requestId nie pasuje do oczekującego żądania — nigdy nie akceptuj niezamówionych danych dostępowych.
Każda apiSession jest jednorazowa — zużywa ją dokładnie jedno wywołanie API. Dwa równoległe wywołania wymagają dwóch osobnych żądań danych dostępowych z różnymi wartościami requestId.
Sesje wygasają po 15 minutach. Żądaj danych dostępowych w momencie wywołania, a nie przy starcie wtyczki.
5. Środowisko widgetu
Ta sekcja opisuje środowisko, w którym działa osadzona aplikacja, oraz sposób jej budowy, tak aby dobrze wyświetlała się w każdym slocie.
Właściwość | Bieżące zachowanie |
Obsługiwane profile | Szansa sprzedaży, Firma, Osoba, Przestrzeń |
Pozycja | Konfigurowalna — umieszczana między sekcjami profilu przez administratora |
Rozmiar | Konfigurowalny — wysokość Mała (240 px), Średnia (380 px) lub Duża (520 px) |
Przewijanie | Zależne od układu samej osadzonej aplikacji |
Wiele widgetów | Obsługiwane — wiele wtyczek może być aktywnych jednocześnie, każda w swoim slocie |
Zalecenia dotyczące responsywności
Slot wtyczki ma konfigurowalną wysokość, ale jego szerokość dostosowuje się do przestrzeni dostępnej w układzie profilu (na przykład zwęża się, gdy otworzy się panel boczny). Zdecydowanie zalecamy budowanie osadzonej aplikacji w płynnym, responsywnym układzie.
Obsłuż co najmniej trzy punkty graniczne (breakpointy) szerokości:
Breakpoint | Zakres szerokości | Uwagi |
micro | < 260 px | ciasne odstępy, mała czcionka |
default | 260–399 px | główny cel projektowy |
wide | ≥ 400 px | więcej przestrzeni |
Prosty punkt wyjścia:
/* In your embedded app's root stylesheet */
html, body {
margin: 0;
padding: 0;
width: 100%;
box-sizing: border-box;
}
Używaj width: 100% na kontenerze głównym zamiast stałej wartości w pikselach.
Unikaj sztywnych breakpointów zakładających minimalną szerokość — slot może być węższy niż typowy widok desktopowy.
Stosuj jednostki względne (%, rem, vw tam, gdzie to zasadne) dla marginesów wewnętrznych i rozmiarów czcionek.
Testuj przy szerokościach od 260 px (breakpoint micro), aby pokryć najbardziej ograniczone scenariusze.
Dzięki temu widget czysto wypełni dostępną szerokość slotu niezależnie od sposobu wyświetlania profilu.