Rozwiązywanie problemów

Typowe problemy i rozwiązania dotyczące integracji i użycia widżetu.

Masz problemy? Jesteś w dobrym miejscu. Ten przewodnik obejmuje najczęstsze problemy, z którymi spotykają się deweloperzy podczas integracji widgetu, wraz z rozwiązaniami krok po kroku. Większość problemów można rozwiązać w zaledwie kilka minut.

50d Szybka wskazówka debugowania

Otwórz konsolę dewelopera w swojej przeglądarce (F12) przed rozpoczęciem rozwiązywania problemów. Większość błędów widgetu wyświetli jasne komunikaty w konsoli, które wskazują bezpośrednio na problem.

Jeśli widget w ogóle nie pojawia się na twojej stronie, postępuj zgodnie z tymi krokami rozwiązywania problemów w kolejności:

❌ Problem: Skrypt widgetu nie ładuje się

Błąd: "Widget nie skonfigurowany" (z szczegółami na temat każdego brakującego atrybutu data-*)

Sprawdź konsolę przeglądarki pod kątem tego komunikatu o błędzie.

✅ Rozwiązanie: Zweryfikuj wymagane atrybuty

Upewnij się, że wszystkie wymagane atrybuty danych są obecne w tagu skryptu:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Problem: Nieudana autoryzacja

Błąd: "Wymagana autoryzacja" lub "Nieprawidłowe dane uwierzytelniające"

Widget nie może się uwierzytelnić z API. Zwykle dzieje się tak, gdy dane uwierzytelniające są nieprawidłowe lub wygasły.

✅ Rozwiązanie: Sprawdź konfigurację OAuth

Problemy z autoryzacją są zazwyczaj łatwe do naprawienia. Przejdź przez te kontrole:

Zweryfikuj, czy client_id jest poprawny w twojej aplikacji OAuth - Skopiuj go bezpośrednio z pulpitu, aby uniknąć literówek
Upewnij się, że aplikacja OAuth jest aktywna i nie jest wyłączona w twoim pulpicie
Sprawdź, czy aplikacja OAuth ma skonfigurowane odpowiednie URI przekierowania - Domeny widgetu muszą być dozwolone
Zweryfikuj, czy domena widgetu jest dozwolona w ustawieniach CORS na twoim backendzie
Jeśli niedawno wygenerowałeś dane uwierzytelniające, upewnij się, że używasz nowych wartości

Wciąż utknąłeś? Spróbuj utworzyć nową aplikację OAuth w swoim pulpicie. Czasami rozpoczęcie od nowa rozwiązuje niejasne problemy z konfiguracją.

❌ Problem: /api/v1/auth/widget-token zwraca 400 (Pochodzenie nie jest dozwolone)

Błąd: "Pochodzenie nie jest dozwolone" lub żądanie tokena widżetu odrzucone

Typowe podczas osadzania w iframe, gdy domena hosta nie jest wymieniona w dozwolonych pochodzeniach OAuth.

✅ Rozwiązanie: Dostosuj pochodzenie hosta i listę dozwolonych OAuth

Dodaj pochodzenie swojej strony osadzającej (na przykład http://localhost:3000) do dozwolonych pochodzeń OAuth.
Użyj pełnego formatu schematu + host (+ port), bez końcowej ścieżki.
Podczas osadzania w iframe upewnij się, że wywołania tokenów przenoszą pochodzenie strony hosta w X-Embed-Origin.
Sprawdź, czy adres URL żądania to /api/v1/auth/widget-token (nie starsze ścieżki).

Wskazówka walidacyjna: Sprawdź zakładkę sieci przeglądarki pod kątem nagłówków żądania tokena i porównaj X-Embed-Origin z wpisem dozwolonych pochodzeń OAuth.

❌ Problem: Widget wydaje się zminimalizowany, ale przycisk jest niewidoczny

Problem z pozycjonowaniem przycisku

Widget ładuje się, ale przycisk znajduje się poza widokiem.

✅ Rozwiązanie: Sprawdź ustawienia pozycjonowania

Zweryfikuj ustawienie pozycji konfiguracji widgetu
Sprawdź konflikty CSS z position: fixed
Upewnij się, że kontenery nadrzędne nie mają overflow: hidden

❌ Problem: Widget ukryty na urządzeniach mobilnych

✅ Rozwiązanie: Dostosuj ustawienia mobilne

Jeśli hide_on_mobile jest włączone w konfiguracji, widget będzie ukryty na urządzeniach mobilnych. Wyłącz to ustawienie lub dostosuj punkt przerwania dla urządzeń mobilnych.

Problemy ze stylami

Problemy wizualne są powszechne i zazwyczaj łatwe do naprawienia. Widget jest zaprojektowany tak, aby był wizualnie izolowany od twojej strony, ale czasami mogą wystąpić konflikty.

❌ Problem: Kolory się nie stosują

✅ Rozwiązanie: Wyczyść pamięć podręczną i sprawdź konfigurację

Postępuj zgodnie z tymi krokami, aby zdiagnozować problemy z kolorami:

Wyczyść pamięć podręczną przeglądarki i przeładuj stronę (Ctrl+Shift+R lub Cmd+Shift+R dla twardego przeładowania)
Zweryfikuj, czy wartości kolorów są poprawnymi kodami szesnastkowymi (muszą zaczynać się od # i mieć 6 znaków, np. #FF5733)
Sprawdź, czy konfiguracja została zapisana w pulpicie - Szukaj potwierdzenia "zapisano"
Upewnij się, że edytujesz poprawną konfigurację - Sprawdź, czy identyfikator konfiguracji pasuje do twojego tagu skryptu
Poczekaj kilka sekund po zapisaniu - Zmiany w konfiguracji mogą zająć 5-10 sekund, aby się propagować

Wskazówka debugowania: Otwórz widget w swojej przeglądarce i użyj narzędzia inspekcji elementów, aby zweryfikować, które wartości CSS są faktycznie stosowane. To pokaże ci, czy twoje kolory ładują się lub są nadpisywane.

❌ Problem: Czcionki się nie ładują

✅ Rozwiązanie: Konfiguracja czcionki

Upewnij się, że rodzina czcionek jest ustawiona na "system-ui" lub czcionkę bezpieczną dla sieci
Niestandardowe czcionki mogą się nie ładować z powodu ograniczeń CORS
Sprawdź, czy wartości font-weight są obsługiwane

Problemy z funkcjonalnością

Gdy widget ładuje się poprawnie, ale funkcje nie działają zgodnie z oczekiwaniami, te rozwiązania pomogą.

❌ Problem: Wiadomości się nie wysyłają

Błąd sieciowy, przekroczenie czasu lub wygasła sesja

Użytkownik wpisuje wiadomość i klika wyślij, ale nic się nie dzieje lub pojawia się błąd. Sprawdź zakładkę sieci przeglądarki pod kątem nieudanych żądań (powinny być wyświetlane na czerwono w zakładce sieci).

✅ Rozwiązanie: Sprawdź sesję i sieć

Problemy z wysyłaniem wiadomości zazwyczaj dotyczą łączności sieciowej lub wygasłych sesji. Diagnozuj systematycznie:

Zweryfikuj, czy punkty końcowe API są dostępne - Spróbuj uzyskać dostęp do adresu URL API bezpośrednio w przeglądarce
Sprawdź, czy token autoryzacyjny jest ważny - Szukaj błędów 401/403 w zakładce sieci
Upewnij się, że sesja nie wygasła - Sesje zazwyczaj trwają 30 minut bezczynności
Sprawdź, czy są problemy z łącznością sieciową - Czy twoje połączenie internetowe jest stabilne?
Szukaj błędów CORS w konsoli - Wskazują one, że twoja domena może nie być na białej liście
Zweryfikuj, czy oprogramowanie zapory/bezpieczeństwa nie blokuje API - Sieci korporacyjne czasami blokują zewnętrzne API

Szybki test: Jeśli wiadomości działają w oknie incognito, ale nie w twojej normalnej przeglądarce, problem prawdopodobnie dotyczy rozszerzeń przeglądarki lub pamięci podręcznej danych uwierzytelniających.

❌ Problem: Przepływy rozmów nie działają

✅ Rozwiązanie: Zweryfikuj konfigurację przepływu

Sprawdź, czy słowa kluczowe wyzwalające dokładnie się zgadzają
Zweryfikuj, czy odpowiedzi przepływu są poprawnie skonfigurowane
Upewnij się, że akcje przycisków są ważne

Problemy z wydajnością

❌ Problem: Widget ładuje się wolno

✅ Rozwiązanie: Optymalizuj ładowanie

Użyj wersji produkcyjnej zamiast deweloperskiej
Włącz pamięć podręczną przeglądarki dla statycznych zasobów
Minimalizuj niestandardowe CSS i obrazy
Rozważ leniwe ładowanie, jeśli nie jest krytyczne

❌ Problem: Wysokie zużycie pamięci

✅ Rozwiązanie: Zmniejsz zużycie zasobów

Ogranicz długość historii wiadomości
Optymalizuj obrazy i multimedia
Wyłącz nieużywane funkcje

Kompatybilność przeglądarki

❌ Problem: Widget nie działa w starszych przeglądarkach

✅ Rozwiązanie: Sprawdź wsparcie przeglądarki

Widget wymaga nowoczesnych funkcji przeglądarki:

Wsparcie JavaScript ES6+
API PostMessage
CSS Grid i Flexbox
Nowoczesne możliwości iframe

Minimalnie wspierane przeglądarki: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Uzyskiwanie pomocy

Gdy potrzebujesz dodatkowej pomocy poza tym przewodnikiem, te narzędzia i zasoby pomogą ci zdiagnozować problemy lub uzyskać wsparcie.

Tryb debugowania

Włącz tryb debugowania, aby zobaczyć szczegółowe logi w konsoli przeglądarki. To dostarcza informacji o tym, co widget robi na każdym kroku:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Narzędzia dewelopera przeglądarki

Sprawdź zakładkę Konsola pod kątem błędów JavaScript
Sprawdź zakładkę Sieć pod kątem nieudanych żądań
Sprawdź zakładkę Aplikacja pod kątem problemów z lokalnym przechowywaniem
Użyj zakładki Elementy, aby zbadać DOM widgetu

Typowe kroki debugowania

Wyczyść pamięć podręczną przeglądarki i pliki cookie
Spróbuj w trybie incognito/prywatnym
Testuj w różnych przeglądarkach
Sprawdź łączność sieciową
Zweryfikuj wszystkie wartości konfiguracji

Wciąż masz problemy?

Sprawdź nasz przewodnik po konfiguracji lub skontaktuj się z pomocą techniczną, przesyłając logi konsoli przeglądarki i szczegóły konfiguracji.

Wstecz

Rozwiązywanie problemów

Typowe problemy i rozwiązania dotyczące integracji i użycia widżetu.

50d Szybka wskazówka debugowania

Jeśli widget w ogóle nie pojawia się na twojej stronie, postępuj zgodnie z tymi krokami rozwiązywania problemów w kolejności:

❌ Problem: Skrypt widgetu nie ładuje się

Błąd: "Widget nie skonfigurowany" (z szczegółami na temat każdego brakującego atrybutu data-*)

Sprawdź konsolę przeglądarki pod kątem tego komunikatu o błędzie.

✅ Rozwiązanie: Zweryfikuj wymagane atrybuty

Upewnij się, że wszystkie wymagane atrybuty danych są obecne w tagu skryptu:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Problem: Nieudana autoryzacja

Błąd: "Wymagana autoryzacja" lub "Nieprawidłowe dane uwierzytelniające"

Widget nie może się uwierzytelnić z API. Zwykle dzieje się tak, gdy dane uwierzytelniające są nieprawidłowe lub wygasły.

✅ Rozwiązanie: Sprawdź konfigurację OAuth

Problemy z autoryzacją są zazwyczaj łatwe do naprawienia. Przejdź przez te kontrole:

Zweryfikuj, czy client_id jest poprawny w twojej aplikacji OAuth - Skopiuj go bezpośrednio z pulpitu, aby uniknąć literówek
Upewnij się, że aplikacja OAuth jest aktywna i nie jest wyłączona w twoim pulpicie
Sprawdź, czy aplikacja OAuth ma skonfigurowane odpowiednie URI przekierowania - Domeny widgetu muszą być dozwolone
Zweryfikuj, czy domena widgetu jest dozwolona w ustawieniach CORS na twoim backendzie
Jeśli niedawno wygenerowałeś dane uwierzytelniające, upewnij się, że używasz nowych wartości

Wciąż utknąłeś? Spróbuj utworzyć nową aplikację OAuth w swoim pulpicie. Czasami rozpoczęcie od nowa rozwiązuje niejasne problemy z konfiguracją.

❌ Problem: /api/v1/auth/widget-token zwraca 400 (Pochodzenie nie jest dozwolone)

Błąd: "Pochodzenie nie jest dozwolone" lub żądanie tokena widżetu odrzucone

Typowe podczas osadzania w iframe, gdy domena hosta nie jest wymieniona w dozwolonych pochodzeniach OAuth.

✅ Rozwiązanie: Dostosuj pochodzenie hosta i listę dozwolonych OAuth

Dodaj pochodzenie swojej strony osadzającej (na przykład http://localhost:3000) do dozwolonych pochodzeń OAuth.
Użyj pełnego formatu schematu + host (+ port), bez końcowej ścieżki.
Podczas osadzania w iframe upewnij się, że wywołania tokenów przenoszą pochodzenie strony hosta w X-Embed-Origin.
Sprawdź, czy adres URL żądania to /api/v1/auth/widget-token (nie starsze ścieżki).

Wskazówka walidacyjna: Sprawdź zakładkę sieci przeglądarki pod kątem nagłówków żądania tokena i porównaj X-Embed-Origin z wpisem dozwolonych pochodzeń OAuth.

❌ Problem: Widget wydaje się zminimalizowany, ale przycisk jest niewidoczny

Problem z pozycjonowaniem przycisku

Widget ładuje się, ale przycisk znajduje się poza widokiem.

✅ Rozwiązanie: Sprawdź ustawienia pozycjonowania

Zweryfikuj ustawienie pozycji konfiguracji widgetu
Sprawdź konflikty CSS z position: fixed
Upewnij się, że kontenery nadrzędne nie mają overflow: hidden

❌ Problem: Widget ukryty na urządzeniach mobilnych

✅ Rozwiązanie: Dostosuj ustawienia mobilne

Jeśli hide_on_mobile jest włączone w konfiguracji, widget będzie ukryty na urządzeniach mobilnych. Wyłącz to ustawienie lub dostosuj punkt przerwania dla urządzeń mobilnych.

Problemy ze stylami

Problemy wizualne są powszechne i zazwyczaj łatwe do naprawienia. Widget jest zaprojektowany tak, aby był wizualnie izolowany od twojej strony, ale czasami mogą wystąpić konflikty.

❌ Problem: Kolory się nie stosują

✅ Rozwiązanie: Wyczyść pamięć podręczną i sprawdź konfigurację

Postępuj zgodnie z tymi krokami, aby zdiagnozować problemy z kolorami:

Wyczyść pamięć podręczną przeglądarki i przeładuj stronę (Ctrl+Shift+R lub Cmd+Shift+R dla twardego przeładowania)
Zweryfikuj, czy wartości kolorów są poprawnymi kodami szesnastkowymi (muszą zaczynać się od # i mieć 6 znaków, np. #FF5733)
Sprawdź, czy konfiguracja została zapisana w pulpicie - Szukaj potwierdzenia "zapisano"
Upewnij się, że edytujesz poprawną konfigurację - Sprawdź, czy identyfikator konfiguracji pasuje do twojego tagu skryptu
Poczekaj kilka sekund po zapisaniu - Zmiany w konfiguracji mogą zająć 5-10 sekund, aby się propagować

❌ Problem: Czcionki się nie ładują

✅ Rozwiązanie: Konfiguracja czcionki

Upewnij się, że rodzina czcionek jest ustawiona na "system-ui" lub czcionkę bezpieczną dla sieci
Niestandardowe czcionki mogą się nie ładować z powodu ograniczeń CORS
Sprawdź, czy wartości font-weight są obsługiwane

Problemy z funkcjonalnością

Gdy widget ładuje się poprawnie, ale funkcje nie działają zgodnie z oczekiwaniami, te rozwiązania pomogą.

❌ Problem: Wiadomości się nie wysyłają

Błąd sieciowy, przekroczenie czasu lub wygasła sesja

✅ Rozwiązanie: Sprawdź sesję i sieć

Problemy z wysyłaniem wiadomości zazwyczaj dotyczą łączności sieciowej lub wygasłych sesji. Diagnozuj systematycznie:

Zweryfikuj, czy punkty końcowe API są dostępne - Spróbuj uzyskać dostęp do adresu URL API bezpośrednio w przeglądarce
Sprawdź, czy token autoryzacyjny jest ważny - Szukaj błędów 401/403 w zakładce sieci
Upewnij się, że sesja nie wygasła - Sesje zazwyczaj trwają 30 minut bezczynności
Sprawdź, czy są problemy z łącznością sieciową - Czy twoje połączenie internetowe jest stabilne?
Szukaj błędów CORS w konsoli - Wskazują one, że twoja domena może nie być na białej liście
Zweryfikuj, czy oprogramowanie zapory/bezpieczeństwa nie blokuje API - Sieci korporacyjne czasami blokują zewnętrzne API

❌ Problem: Przepływy rozmów nie działają

✅ Rozwiązanie: Zweryfikuj konfigurację przepływu

Sprawdź, czy słowa kluczowe wyzwalające dokładnie się zgadzają
Zweryfikuj, czy odpowiedzi przepływu są poprawnie skonfigurowane
Upewnij się, że akcje przycisków są ważne

Problemy z wydajnością

❌ Problem: Widget ładuje się wolno

✅ Rozwiązanie: Optymalizuj ładowanie

Użyj wersji produkcyjnej zamiast deweloperskiej
Włącz pamięć podręczną przeglądarki dla statycznych zasobów
Minimalizuj niestandardowe CSS i obrazy
Rozważ leniwe ładowanie, jeśli nie jest krytyczne

❌ Problem: Wysokie zużycie pamięci

✅ Rozwiązanie: Zmniejsz zużycie zasobów

Ogranicz długość historii wiadomości
Optymalizuj obrazy i multimedia
Wyłącz nieużywane funkcje

Kompatybilność przeglądarki

❌ Problem: Widget nie działa w starszych przeglądarkach

✅ Rozwiązanie: Sprawdź wsparcie przeglądarki

Widget wymaga nowoczesnych funkcji przeglądarki:

Wsparcie JavaScript ES6+
API PostMessage
CSS Grid i Flexbox
Nowoczesne możliwości iframe

Minimalnie wspierane przeglądarki: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Uzyskiwanie pomocy

Gdy potrzebujesz dodatkowej pomocy poza tym przewodnikiem, te narzędzia i zasoby pomogą ci zdiagnozować problemy lub uzyskać wsparcie.

Tryb debugowania

Włącz tryb debugowania, aby zobaczyć szczegółowe logi w konsoli przeglądarki. To dostarcza informacji o tym, co widget robi na każdym kroku:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Narzędzia dewelopera przeglądarki

Sprawdź zakładkę Konsola pod kątem błędów JavaScript
Sprawdź zakładkę Sieć pod kątem nieudanych żądań
Sprawdź zakładkę Aplikacja pod kątem problemów z lokalnym przechowywaniem
Użyj zakładki Elementy, aby zbadać DOM widgetu

Typowe kroki debugowania

Wyczyść pamięć podręczną przeglądarki i pliki cookie
Spróbuj w trybie incognito/prywatnym
Testuj w różnych przeglądarkach
Sprawdź łączność sieciową
Zweryfikuj wszystkie wartości konfiguracji

Wciąż masz problemy?

Sprawdź nasz przewodnik po konfiguracji lub skontaktuj się z pomocą techniczną, przesyłając logi konsoli przeglądarki i szczegóły konfiguracji.

Wstecz

Rozwiązywanie problemów

Widget nie ładuje się

❌ Problem: Skrypt widgetu nie ładuje się

✅ Rozwiązanie: Zweryfikuj wymagane atrybuty

❌ Problem: Nieudana autoryzacja

✅ Rozwiązanie: Sprawdź konfigurację OAuth

❌ Problem: /api/v1/auth/widget-token zwraca 400 (Pochodzenie nie jest dozwolone)

✅ Rozwiązanie: Dostosuj pochodzenie hosta i listę dozwolonych OAuth

Widget niewidoczny

❌ Problem: Widget wydaje się zminimalizowany, ale przycisk jest niewidoczny

✅ Rozwiązanie: Sprawdź ustawienia pozycjonowania

❌ Problem: Widget ukryty na urządzeniach mobilnych

✅ Rozwiązanie: Dostosuj ustawienia mobilne

Problemy ze stylami

❌ Problem: Kolory się nie stosują

✅ Rozwiązanie: Wyczyść pamięć podręczną i sprawdź konfigurację

❌ Problem: Czcionki się nie ładują

✅ Rozwiązanie: Konfiguracja czcionki

Problemy z funkcjonalnością

❌ Problem: Wiadomości się nie wysyłają

✅ Rozwiązanie: Sprawdź sesję i sieć

❌ Problem: Przepływy rozmów nie działają

✅ Rozwiązanie: Zweryfikuj konfigurację przepływu

Problemy z wydajnością

❌ Problem: Widget ładuje się wolno

✅ Rozwiązanie: Optymalizuj ładowanie

❌ Problem: Wysokie zużycie pamięci

✅ Rozwiązanie: Zmniejsz zużycie zasobów

Kompatybilność przeglądarki

❌ Problem: Widget nie działa w starszych przeglądarkach

✅ Rozwiązanie: Sprawdź wsparcie przeglądarki

Uzyskiwanie pomocy

Tryb debugowania

Narzędzia dewelopera przeglądarki

Typowe kroki debugowania

Rozwiązywanie problemów

Widget nie ładuje się

❌ Problem: Skrypt widgetu nie ładuje się

✅ Rozwiązanie: Zweryfikuj wymagane atrybuty

❌ Problem: Nieudana autoryzacja

✅ Rozwiązanie: Sprawdź konfigurację OAuth

❌ Problem: /api/v1/auth/widget-token zwraca 400 (Pochodzenie nie jest dozwolone)

✅ Rozwiązanie: Dostosuj pochodzenie hosta i listę dozwolonych OAuth

Widget niewidoczny

❌ Problem: Widget wydaje się zminimalizowany, ale przycisk jest niewidoczny

✅ Rozwiązanie: Sprawdź ustawienia pozycjonowania

❌ Problem: Widget ukryty na urządzeniach mobilnych

✅ Rozwiązanie: Dostosuj ustawienia mobilne

Problemy ze stylami

❌ Problem: Kolory się nie stosują

✅ Rozwiązanie: Wyczyść pamięć podręczną i sprawdź konfigurację

❌ Problem: Czcionki się nie ładują

✅ Rozwiązanie: Konfiguracja czcionki

Problemy z funkcjonalnością

❌ Problem: Wiadomości się nie wysyłają

✅ Rozwiązanie: Sprawdź sesję i sieć

❌ Problem: Przepływy rozmów nie działają

✅ Rozwiązanie: Zweryfikuj konfigurację przepływu

Problemy z wydajnością

❌ Problem: Widget ładuje się wolno

✅ Rozwiązanie: Optymalizuj ładowanie

❌ Problem: Wysokie zużycie pamięci

✅ Rozwiązanie: Zmniejsz zużycie zasobów

Kompatybilność przeglądarki

❌ Problem: Widget nie działa w starszych przeglądarkach

✅ Rozwiązanie: Sprawdź wsparcie przeglądarki

Uzyskiwanie pomocy

Tryb debugowania

Narzędzia dewelopera przeglądarki

Typowe kroki debugowania