Rozwiązywanie problemów

Typowe problemy i rozwiązania dotyczące integracji i użytkowania widgetów.

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

🔍 Szybka wskazówka debugowania

Otwórz konsolę dewelopera swojej przeglądarki (F12) przed rozwiązywaniem 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, wykonaj te kroki rozwiązywania problemów w kolejności:

❌ Problem: Skrypt widgetu nie ładuje się

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

Sprawdź konsolę przeglądarki w poszukiwaniu tego komunikatu o błędzie.

✅ Rozwiązanie: Weryfikacja wymaganych atrybutów

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: Uwierzytelnienie nie powiodło się

Błąd: "Wymagane uwierzytelnienie" lub "Nieprawidłowe poświadczenia"

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

✅ Rozwiązanie: Sprawdź konfigurację OAuth

Problemy z uwierzytelnieniem są zazwyczaj proste do naprawienia. Pracuj przez te kontrole:

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

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

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

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

Często występuje podczas osadzania w iframe, a 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 zawierają 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 w celu nagłówków żądania tokena i porównaj X-Embed-Origin z wpisem dozwolonych pochodzeń OAuth.

❌ Problem: Widget wydaje się złożony, ale przycisk jest niewidoczny

Problem z pozycjonowaniem przycisku

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

✅ Rozwiązanie: Sprawdź pozycjonowanie konfiguracji

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ę

Wykonaj te kroki, 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 na pulpicie nawigacyjnym - 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 grubości czcionek są wspierane

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 sieci, 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 w poszukiwaniu nieudanych żądań (powinny być oznaczone 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 uwierzytelniający 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
Sprawdź, czy zapora/firewall nie blokuje API - Sieci korporacyjne czasami blokują zewnętrzne API

Szybki test: Jeśli wiadomości działają w trybie incognito, ale nie w 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 pasują
Zweryfikuj, czy odpowiedzi przepływu są poprawnie skonfigurowane
Upewnij się, że akcje przycisków są ważne

Problemy z wydajnością

❌ Problem: Widget ładowany powoli

✅ Rozwiązanie: Optymalizuj ładowanie

Użyj wersji produkcyjnej zamiast deweloperskiej
Włącz pamięć podręczną przeglądarki dla statycznych zasobów
Zminimalizuj niestandardowy 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

Kiedy 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 w celu błędów JavaScript
Sprawdź zakładkę Sieć w celu nieudanych żądań
Sprawdź zakładkę Aplikacja w celu problemów z lokalnym magazynem
Użyj zakładki Elementy, aby sprawdzić DOM widgetu

Typowe kroki debugowania

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

Wciąż masz problemy?

Sprawdź nasz przewodnik konfiguracyjny 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żytkowania widgetów.

🔍 Szybka wskazówka debugowania

Jeśli widget w ogóle nie pojawia się na Twojej stronie, wykonaj te kroki rozwiązywania problemów w kolejności:

❌ Problem: Skrypt widgetu nie ładuje się

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

Sprawdź konsolę przeglądarki w poszukiwaniu tego komunikatu o błędzie.

✅ Rozwiązanie: Weryfikacja wymaganych atrybutów

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: Uwierzytelnienie nie powiodło się

Błąd: "Wymagane uwierzytelnienie" lub "Nieprawidłowe poświadczenia"

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

✅ Rozwiązanie: Sprawdź konfigurację OAuth

Problemy z uwierzytelnieniem są zazwyczaj proste do naprawienia. Pracuj przez te kontrole:

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

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

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

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

Często występuje podczas osadzania w iframe, a 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 zawierają 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 w celu nagłówków żądania tokena i porównaj X-Embed-Origin z wpisem dozwolonych pochodzeń OAuth.

❌ Problem: Widget wydaje się złożony, ale przycisk jest niewidoczny

Problem z pozycjonowaniem przycisku

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

✅ Rozwiązanie: Sprawdź pozycjonowanie konfiguracji

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ę

Wykonaj te kroki, 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 na pulpicie nawigacyjnym - 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 grubości czcionek są wspierane

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 sieci, 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 uwierzytelniający 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
Sprawdź, czy zapora/firewall 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 pasują
Zweryfikuj, czy odpowiedzi przepływu są poprawnie skonfigurowane
Upewnij się, że akcje przycisków są ważne

Problemy z wydajnością

❌ Problem: Widget ładowany powoli

✅ Rozwiązanie: Optymalizuj ładowanie

Użyj wersji produkcyjnej zamiast deweloperskiej
Włącz pamięć podręczną przeglądarki dla statycznych zasobów
Zminimalizuj niestandardowy 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

Kiedy 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 w celu błędów JavaScript
Sprawdź zakładkę Sieć w celu nieudanych żądań
Sprawdź zakładkę Aplikacja w celu problemów z lokalnym magazynem
Użyj zakładki Elementy, aby sprawdzić DOM widgetu

Typowe kroki debugowania

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

Wciąż masz problemy?

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

Wstecz

Rozwiązywanie problemów

Widget się nie ładuje

❌ Problem: Skrypt widgetu nie ładuje się

✅ Rozwiązanie: Weryfikacja wymaganych atrybutów

❌ Problem: Uwierzytelnienie nie powiodło się

✅ 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ę złożony, ale przycisk jest niewidoczny

✅ Rozwiązanie: Sprawdź pozycjonowanie konfiguracji

❌ 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 ładowany powoli

✅ 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 się nie ładuje

❌ Problem: Skrypt widgetu nie ładuje się

✅ Rozwiązanie: Weryfikacja wymaganych atrybutów

❌ Problem: Uwierzytelnienie nie powiodło się

✅ 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ę złożony, ale przycisk jest niewidoczny

✅ Rozwiązanie: Sprawdź pozycjonowanie konfiguracji

❌ 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 ładowany powoli

✅ 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