Dokumentacja

LimeControl — przewodnik

LimeControl to aplikacja PWA do zarządzania instancjami LimeSurvey przez oficjalne API RemoteControl 2 (JSON-RPC, remotecontrol_handle). Działa w przeglądarce na telefonie i komputerze, można ją zainstalować na ekranie głównym. Dostępna jest też bezpłatna aplikacja na iOS i Androida.

Wymagania: LimeSurvey 3.x, 5.x, 6.x lub 7.x z włączonym interfejsem JSON-RPC, konto LimeSurvey z odpowiednimi uprawnieniami oraz konto Google do logowania w aplikacji.

Szybki start

  1. W panelu LimeSurvey włącz interfejs JSON-RPC (instrukcja).
  2. Otwórz app.limecontrol.eu i zaloguj się kontem Google.
  3. W zakładce Instancje dodaj profil: nazwa, adres serwera (wystarczy np. https://ankiety.twojafirma.pl), login i hasło.
  4. Kliknij Połącz. Aplikacja pobierze nazwę instancji i listę ankiet.
  5. Przejdź do zakładki Ankiety i korzystaj z menu szybkich akcji przy każdej ankiecie.

Jeśli pojawi się błąd połączenia, sprawdź panel Log RPC i sekcję CORS i HTTPS.

Instalacja na telefonie

LimeControl jest progresywną aplikacją webową — instaluje się bez sklepu z aplikacjami i aktualizuje automatycznie.

  • Android (Chrome, Edge): przycisk Zainstaluj PWA w aplikacji lub menu przeglądarki → Dodaj do ekranu głównego.
  • iPhone / iPad (Safari): Udostępnij → Do ekranu początkowego.
  • Komputer (Chrome, Edge): ikona instalacji w pasku adresu.

Gdy urządzenie traci połączenie z siecią, aplikacja pokazuje wskaźnik trybu offline. Operacje na ankietach wymagają dostępu do serwera LimeSurvey.

Włączenie API w LimeSurvey

  1. Zaloguj się do panelu LimeSurvey jako superadministrator.
  2. Przejdź do Konfiguracja → Ustawienia globalne → Interfejsy (Configuration → Global settings → Interfaces).
  3. W polu Interfejs RPC wybierz JSON-RPC.
  4. Opcja Publikuj interfejs API nie jest wymagana — ustaw ją zgodnie ze swoją polityką bezpieczeństwa. Kliknij Zapisz.

Domyślny adres API:

# przyjazne adresy URL włączone
https://twoja-instancja.pl/index.php/admin/remotecontrol

# przyjazne adresy URL wyłączone
https://twoja-instancja.pl/index.php?r=admin/remotecontrol

W aplikacji wystarczy wpisać adres bazowy — ścieżka /index.php/admin/remotecontrol zostanie dodana automatycznie.

Uprawnienia konta LimeSurvey

Konto użyte w profilu połączenia powinno mieć uprawnienia:

ObszarUprawnieniaDo czego
AnkietyView/Read, Update, Create, ActivateLista, aktywacja, daty, zamykanie, kopiowanie
Uczestnicy / tokenyZarządzanieTabela tokenów, zaproszenia, przypomnienia
OdpowiedziExportPobieranie wyników CSV / XLS / JSON

Wtyczka uwierzytelniania: zostaw Authdb dla zwykłych kont LimeSurvey albo wpisz nazwę używanej wtyczki, np. AuthLDAP.

Dobra praktyka: utwórz osobne konto LimeSurvey tylko dla LimeControl, z uprawnieniami ograniczonymi do potrzebnych ankiet.

Tryby połączenia

Każdy profil instancji ma własny tryb połączenia:

Bezpośredni (domyślny)

Przeglądarka wysyła zapytania JSON-RPC prosto do serwera LimeSurvey. Dane nie przechodzą przez serwery LimeControl. Wymaga HTTPS i nagłówków CORS po stronie LimeSurvey.

Przekaźnik serwerowy

Gdy nie możesz zmienić konfiguracji serwera LimeSurvey, wybierz w profilu Przekaźnik serwerowy (obejście CORS). Zapytania trafiają wtedy do /api/rpc-relay na serwerze aplikacji i stamtąd do LimeSurvey.

W trybie przekaźnika login, hasło i dane ankiet przechodzą przez serwer aplikacji (nie są tam zapisywane). Używaj go tylko wtedy, gdy tryb bezpośredni nie jest możliwy.

Aplikacja natywna

Aplikacja mobilna LimeControl działa natywnie na iOS i Androidzie i nie podlega ograniczeniom CORS.

CORS i HTTPS

Aplikacja działa przez HTTPS, więc serwer LimeSurvey również musi być dostępny przez HTTPS — przeglądarki blokują zapytania do adresów http:// (mixed content).

Serwer musi też zwracać nagłówki CORS, także dla zapytań wstępnych OPTIONS. Zamiast * możesz wpisać konkretną domenę aplikacji.

Apache (.htaccess lub VirtualHost)

Header always set Access-Control-Allow-Origin "https://app.limecontrol.eu"
Header always set Access-Control-Allow-Methods "POST, OPTIONS"
Header always set Access-Control-Allow-Headers "Content-Type, Accept"

Nginx

add_header Access-Control-Allow-Origin "https://app.limecontrol.eu" always;
add_header Access-Control-Allow-Methods "POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, Accept" always;

Jeśli nie masz dostępu do konfiguracji serwera, użyj trybu przekaźnika serwerowego.

LimeSurvey 7.x

W formularzu profilu wybierz wersję LimeSurvey 7.x (daty UTC + nowe kody błędów) (opcja Automatyczna zachowuje domyślne zachowanie RC2). Aplikacja wtedy:

  • przelicza daty startdate i expires oraz terminy harmonogramu na UTC,
  • rozpoznaje nowe kody błędów RemoteControl 2 i pokazuje czytelne komunikaty,
  • obsługuje nowe identyfikatory pól w inspektorze get_fieldmap.

W LimeSurvey 7.9+ możesz włączyć rejestr wywołań API po stronie serwera w application/config/config.php:

'config' => array(
    'rpc_log' => true,
)

Logi trafiają do tmp/runtime/remotecontrol.log, a hasła i klucze sesji są w nich maskowane.

Instancje

Zakładka Instancje przechowuje profile serwerów LimeSurvey. Profile są zapisywane w chmurze (Cloud Firestore) i przypisane do Twojego konta Google, więc są dostępne na każdym urządzeniu.

  • Wyszukiwanie i filtrowanie profili po nazwie, adresie, użytkowniku lub wtyczce logowania oraz po trybie połączenia (Wszystkie, Bezpośredni, Przekaźnik).
  • Wybór wersji LimeSurvey dla każdego profilu.
  • Log RPC — lista wywołań API z czasem odpowiedzi i diagnozą błędów (np. CORS).

Ankiety

Lista ankiet z wyszukiwarką i filtrem Wszystkie / Aktywne / Nieaktywne. Menu szybkich akcji przy każdej ankiecie pozwala:

  • Aktywować ankietę (activate_survey), opcjonalnie razem z tabelą tokenów (activate_tokens).
  • Ustawić okno dostępności — daty rozpoczęcia i zakończenia (set_survey_properties).
  • Zamknąć aktywną ankietę.
  • Skopiować ankietę (copy_survey).
  • Przejść do harmonogramu lub uczestników wybranej ankiety.

Statystyki i eksport

Dla każdej ankiety dostępne jest podsumowanie odpowiedzi i tokenów (get_summary) z wykresami oraz porównanie dwóch ankiet obok siebie.

Eksport odpowiedzi (export_responses) do formatów:

  • CSV — do arkuszy i narzędzi analitycznych,
  • Excel (.xls),
  • JSON — do dalszego przetwarzania.

Inspektor kolumn (get_fieldmap) pokazuje, jak nazywają się pola w eksporcie — zarówno w starszym formacie SGQA, jak i w nowym formacie LimeSurvey 7.

Harmonogram aktywacji

Zaplanuj aktywację ankiety na wybrany dzień i godzinę. Zadanie wykonuje serwer aplikacji, więc zadziała nawet po zamknięciu aplikacji na telefonie.

W chwili startu serwer wykonuje kolejno:

get_session_key
  → activate_survey
  → activate_tokens        # opcjonalnie
  → set_survey_properties  # opcjonalnie: data zakończenia (expires)
  → release_session_key
  • Kolejka jest sprawdzana co 15 sekund.
  • Każde zadanie ma szczegółowy log kroków RPC.
  • Uruchom teraz wykonuje zadanie natychmiast — przydatne do testu.
  • Zaplanowane zadanie można anulować lub usunąć z historii.
  • Hasło jest usuwane z zadania zaraz po jego wykonaniu lub anulowaniu.

O wyniku zadania (sukces lub błąd) informuje powiadomienie w aplikacji.

Uczestnicy i szablony e-mail

Uczestnicy (tokeny)

  • Inicjalizacja tabeli tokenów jednym dotknięciem.
  • Lista uczestników z filtrem niewykorzystanych tokenów.
  • Dodawanie i usuwanie respondentów.

Edytor szablonów

Edytuj temat i treść zaproszenia oraz przypomnienia dla każdego języka ankiety. Edytor ma podgląd wiadomości na przykładowych danych i szybkie wstawianie znaczników:

{FIRSTNAME} {LASTNAME} {EMAIL} {TOKEN} {SURVEYURL} {OPTOUTURL} {SURVEYNAME}

Przyciski Zapisz i wyślij zaproszenia oraz Zapisz i wyślij przypomnienia zapisują szablon i od razu wysyłają zaproszenia (invite_participants) lub przypomnienia (remind_participants).

Wysyłka e-maili korzysta z konfiguracji poczty Twojego serwera LimeSurvey. Sprawdź ją w LimeSurvey przed pierwszą wysyłką.

Aplikacja mobilna

LimeControl jest dostępny jako bezpłatna aplikacja na iOS (App Store) i Androida (Google Play). Linki do sklepów znajdziesz w zakładce Instancje → Aplikacja mobilna.

Aplikacja natywna łączy się bezpośrednio z LimeSurvey i nie wymaga nagłówków CORS.

Obsługiwane metody API

ObszarMetodyZastosowanie
Sesjaget_session_key, release_session_key, get_site_settingsLogowanie, zamknięcie sesji, nazwa instancji
Ankietylist_surveys, get_survey_properties, set_survey_properties, activate_survey, copy_surveyLista, aktywacja, daty, zamykanie, kopiowanie
Statystyki i eksportget_summary, get_fieldmap, export_responsesPodsumowania, porównania, inspektor kolumn, eksport
Uczestnicyactivate_tokens, list_participants, add_participants, delete_participants, invite_participants, remind_participantsTabela tokenów, zaproszenia, przypomnienia
Szablony e-mailget_language_properties, set_language_propertiesOdczyt i zapis treści zaproszeń i przypomnień

Bezpieczeństwo i prywatność

  • Logowanie Google (Firebase Authentication) chroni dostęp do Twoich profili.
  • Profile serwerów są zapisywane w Cloud Firestore; reguły bazy pozwalają je czytać i zmieniać wyłącznie właścicielowi konta.
  • Hasła do LimeSurvey nie są zapisywane ani w Firestore, ani w localStorage. Opcja „Zapamiętaj hasło tylko w pamięci tej sesji” trzyma je wyłącznie w pamięci otwartej karty.
  • Tryb bezpośredni — dane ankiet trafiają wprost z serwera LimeSurvey do Twojej przeglądarki.
  • Harmonogram — hasło potrzebne do aktywacji jest przechowywane na serwerze aplikacji tylko do momentu wykonania lub anulowania zadania.

Rozwiązywanie problemów

ObjawPrzyczyna i rozwiązanie
Błąd CORS / Failed to fetchBrak nagłówków CORS na serwerze LimeSurvey. Dodaj je (przykłady) lub przełącz profil na przekaźnik serwerowy.
Blokada mixed contentSerwer LimeSurvey działa przez http://. Włącz HTTPS na serwerze.
Invalid user name or passwordSprawdź login, hasło i wtyczkę uwierzytelniania (Authdb, AuthLDAP).
404 lub odpowiedź HTML zamiast JSONInterfejs JSON-RPC jest wyłączony albo adres API jest inny — wpisz pełną ścieżkę z ?r=admin/remotecontrol.
No permissionKonto nie ma wymaganych uprawnień do danej ankiety.
Przesunięte godziny datUstaw w profilu wersję LimeSurvey 7.x (daty w UTC) lub sprawdź strefę czasową serwera.

Szczegóły każdego wywołania znajdziesz w panelu Log RPC w zakładce Instancje.

Gotowy, by zacząć?

Dodaj swoją pierwszą instancję LimeSurvey w kilka minut.