Dokumentacja — Avelis

Czym jest Avelis

Avelis to platforma SaaS do zbierania opinii w Google. Każdemu klientowi tworzona jest brandowana strona lądowania pod adresem getavelis.pl/{slug}. Na tę stronę prowadzą fizyczne kody QR lub tagi NFC, które są rozdawane klientom biznesu.

📱

Klient skanuje QR lub dotyka tagu NFC

→

🌐

Otwiera się brandowana strona lądowania

→

⭐

Klika przycisk i zostawia opinię w Google

Wszystkie interakcje są rejestrowane — otwarcia strony, kliknięcia przycisku i nowe opinie.

Rejestracja i logowanie

Nowy użytkownik

Otworzyć /login → kliknąć Sign in with Google
Zalogować się przez konto Google
Otworzy się strona wyboru: powiąż istniejący lub utwórz nowy biznes
Przy tworzeniu nowego — wypełnić: nazwę, adres URL strony (slug), link do Google Reviews
Gotowe — przejść do pulpitu /my

Istniejący klient (stare logowanie)

Otworzyć /login/legacy — zalogować się przez username i hasło
W pulpicie pojawi się niebieska plansza Connect your Google account
Kliknąć Connect — zalogować się przez Google
Konto Google powiązane. Kolejne logowania — tylko przez Google

Strona lądowania

Każdy biznes jest dostępny pod adresem getavelis.pl/{slug}. Strona wyświetla brandowaną kartę i przycisk przejścia do Google Reviews.

Parametr source

URL może zawierać parametr ?source= — jest on rejestrowany w statystykach:

/{slug}?source=qr — skanowanie kodu QR

/{slug}?source=nfc — dotknięcie tagu NFC

/{slug} — bezpośrednie przejście (direct)

Co się dzieje przy otwarciu

Rejestrowane jest zdarzenie landing_open ze źródłem (qr / nfc / direct)
Deduplikacja: ponowne otwarcie w ciągu 30 sekund nie jest liczone
Wyświetlana jest karta biznesu zgodnie z ustawieniami motywu, układu i treści

Przycisk Google Reviews

Po kliknięciu przycisku «Zostaw opinię w Google» serwer rejestruje zdarzenie google_click i przekierowuje na Google Review URL biznesu. Kliknięcie jest rejestrowane po stronie serwera — niezawodnie, bez zależności od JavaScript.

Wyłączona strona

Administrator może wyłączyć stronę biznesu. Zamiast karty zostanie wyświetlony komunikat «Strona tymczasowo niedostępna». Wyłączone strony nie rejestrują zdarzeń.

Pulpit i statystyki

Dostępny pod adresem /my. Zawiera trzy zakładki: Przegląd, Opinie i Ustawienia. Na komputerze — nawigacja boczna. Na urządzeniach mobilnych — pasek nawigacji na dole.

Selektor okresu (7 / 30 / 90 dni) filtruje wszystkie delty KPI i liczby nowych opinii. Na urządzeniach mobilnych pojawia się w górnym pasku.

Karty KPI

⭐ Ocena Google

Aktualna ocena z Google Business Profile, rząd gwiazdek i łączna liczba opinii. Wymaga połączenia GBP.

💬 Nowe opinie

Opinie otrzymane w wybranym okresie z deltą % względem poprzedniego równoważnego okresu. Wymaga połączenia GBP.

📊 Aktywność klientów

Trzy liczby za wybrany okres: interakcje (otwarcia strony), → Google (kliknięcia przycisku), nowe opinie (opinie GBP).

👁 Otwarcia strony

Otwarcia strony lądowania w wybranym okresie. Pod wartością — delta (+/−) względem poprzedniego okresu.

🔗 Kliknięcia Google

Kliknięcia przycisku Google Reviews w wybranym okresie. Delta vs poprzedni okres.

🏆 Cel miesięczny

Pasek postępu pokazujący łączną liczbę opinii względem celu ustawionego w polu Reviews goal. Pokazuje dni pozostałe w miesiącu. Widoczny tylko gdy Reviews goal jest ustawiony.

Wykresy

Daily scans

Liniowy wykres SVG skanowań z ostatnich 30 dni z wypełnieniem pod linią. Etykiety dat na osi X.

Sources

Wykres pierścieniowy udziału źródeł: QR (niebieski) / NFC (złoty) / Direct (szary). Legenda z procentami i liczbami.

Panele informacyjne

Ostatnie skany — ostatnie 8 skanowań z kolorowym wskaźnikiem źródła i znacznikiem czasu
Zakładka Opinie — ostatnie opinie pobrane z Google Business Profile przez GBP API. Wymaga połączenia GBP.
Info — data pierwszego i ostatniego skanowania, link do Google Review URL, sekcja Google Business Profile

Ustawienia strony

Wszystkie ustawienia są dostępne na zakładce Settings w /my. Po prawej wyświetlany jest podgląd na żywo — zmiany widoczne od razu, bez zapisywania.

Business Name

Nazwa biznesu. Można ukryć przyciskami Show / Hide.

Design Theme

Schemat kolorów karty. 8 motywów — więcej w sekcji Motywy.

Layout

Struktura karty. 4 warianty — więcej w sekcji Układy.

Logo / Photo

Załadowanie własnego obrazu. Maks. 5 MB, formaty: PNG, JPG, WebP.

Logo Symbol

Wbudowane ikony SVG (bez przesyłania pliku). Style: Outline / Filled. 10 kolorów.

Background Color

8 presetów gradientu dla tła karty: Aurora, Sunset, Forest, Marble, Lavender, Midnight, Rose, Sage.

Background Photo

Przesyłanie zdjęcia lub wybór spośród 7 presetów: Clinic, Beauty, Nightlife, Nature, Cafe, Restaurant, Fitness.

Image Fit

Contain — dopasuj | Cover — wypełnij | Stretch — rozciągnij.

Position

Wyrównanie logo: Top / Center / Bottom.

Border

Gradientowa ramka wokół logo: None / Purple / Sunset / Gold / Emerald / Brown / Bronze / Mocha.

Google Review URL

Link, pod który trafi klient po kliknięciu przycisku. Format: https://search.google.com/local/writereview?placeid=...

Email do alertów

Email dla powiadomień o braku aktywności. Jeśli nie podano — używany jest email konta Google.

Próg braku aktywności (dni)

Po ilu dniach bez skanowań wysłać pierwszy alert. Drugi po 2×N. Puste = domyślnie 7 i 14 dni.

Cel opinii

Docelowa łączna liczba opinii. Wyświetlana jako pasek postępu w kafelku Cel miesięczny na mobilnym pulpicie. Pozostaw puste, aby ukryć ten kafelek.

Motywy

Motyw definiuje paletę kolorów karty przez zmienne CSS. Stosowany jest klasą theme-{key}.

Default Białe tło, ciemny tekst

Dark Ciemnoniebieskie, jasny tekst

Ocean Nasycony niebieski

Warm Ciepły kremowy

Clinic Zimny błękitny

Lumière Złocisto-beżowy

Noir Czarny ze złotem

Sage Zielony, naturalny

Układy

Układ określa strukturę i rozmieszczenie elementów karty.

Classic

Pionowa karta. Logo u góry, nazwa, opis, przycisk. Wersja uniwersalna.

Hero

Duże zdjęcie / logo w górnej części na pełną szerokość. Efektowne dla restauracji i salonów.

Circle

Logo w okrągłej ramce na środku. Klasyczny wygląd brandingowy.

Poster

Zdjęcie wewnątrz koła z efektem «posteru». Odpowiednie dla zdjęć portretowych.

Treść i tłumaczenia

Wszystkie elementy tekstowe obsługują dwa języki: polski 🇵🇱 i angielski 🇬🇧.

Przełącznik języka wyświetlany jest na karcie. Jeśli tłumaczenie nie jest wypełnione — używany jest tekst domyślny.

Edytowalne pola tekstowe

Welcome Text

Krótkie powitanie pod nazwą biznesu.

Heading

Nagłówek wezwania do działania. Domyślnie: «Dziękujemy za wizytę!»

Description

Opis pod nagłówkiem. Domyślnie: «Twoja opinia pomaga innym...»

Tile 1 / Tile 2

Dwa bloki informacyjne z ikoną. Przykłady: «30 sekund», «Pomagasz nam rosnąć».

Button

Tekst przycisku. Domyślnie: «Zostaw opinię w Google»

Footer note

Mały podpis na dole. Domyślnie: «Opinia zostanie dodana bezpośrednio w Google.»

Dostępne ikony dla kafelków

Zegar

Tarcza

Gwiazdka

Serce

Kciuk

Uśmiech

Błyskawica

Puchar

Ludzie

Wzrost

Prezent

Fajka

Opinia

Nagroda

Logo i tło

Logo (wgrywanie)

Formaty: PNG, JPG, WebP
Maksymalny rozmiar: 5 MB
Przechowywane w MinIO — osobnym magazynie plików na serwerze. Pliki nie są tracone przy aktualizacji aplikacji i przechowywane są niezależnie od bazy danych.
Przeglądarka pobiera przez proxy /logo/{key} — bezpośredni dostęp do MinIO jest zablokowany
Przy wgrywaniu nowego logo stare jest automatycznie usuwane

Wbudowane symbole SVG

Jeśli logo nie jest wgrane — można wybrać symbol z zestawu (restauracja, medycyna, uroda itp.). Symbol renderowany jest jako inline SVG i obsługuje kolor motywu (currentColor).

Outline · auto

Filled · niebieski

Filled · zielony

Filled · pomarańczowy

Filled · fioletowy

Zdjęcia tła (presety)

Clinic Beauty Nightlife Nature Cafe Restaurant Fitness

Gradienty tła (presety)

Aurora

Sunset

Forest

Marble

Lavender

Midnight

Rose

Sage

Jak wygląda na karcie

Aurora

Sunset

Midnight

Zdjęcie + przyciemnienie

Google Business Profile

Połączenie Google Business Profile pozwala widzieć aktualną ocenę i liczbę opinii bezpośrednio w pulpicie. Synchronizacja odbywa się automatycznie co 6 godzin.

Jak podłączyć

Otworzyć pulpit /my
W kafelku Google Business (zakładka Statistics) kliknąć Połącz GBP
Zalogować się przez Google (potrzebne konto z zweryfikowanym biznesem)
Wybrać odpowiednią lokalizację z listy
Kliknąć Połącz tę lokalizację

Co wyświetla się po podłączeniu

Ocena Google

Średnia ocena ⭐ i łączna liczba opinii

Synchronizacja

Data i godzina ostatniej synchronizacji z Google

Wymagania: Aby podłączyć GBP, potrzebny jest zweryfikowany biznes na business.google.com. Bez weryfikacji lista lokalizacji będzie pusta.

Powiadomienia o braku aktywności

Jeśli tabliczka QR nie była skanowana przez kilka dni — system automatycznie wysyła powiadomienie email na adres klienta.

Progi wyzwalania (domyślne)

7 dni

Pierwsze ostrzeżenie. Sprawdź umiejscowienie tabliczki.

14 dni ⚠️

Eskalacja. Tabliczka długo nieużywana.

Jak działa

Sprawdzanie w tle uruchamiane jest raz na 24 godziny
Sprawdzana jest data ostatniego zdarzenia landing_open
Jeśli aktywność wznowiła się — licznik i flagi są resetowane
Powtórne alerty za jeden okres nieaktywności nie są wysyłane

Konfiguracja email i progu

W ustawieniach (Settings → Powiadomienia) można podać email dla alertów. Jeśli nie podano — używany jest email konta Google.

Pole «Próg braku aktywności» pozwala ustawić własną liczbę dni (N). Pierwszy alert przyjdzie po N dniach, drugi po 2×N. Pozostaw puste, aby używać wartości domyślnych (7 i 14 dni).

Często zadawane pytania

Gdzie znaleźć link do Google Reviews?

Otwórz Google Maps, znajdź swoją organizację, kliknij «Pobierz link» lub wejdź do Google Business Profile i skopiuj link z sekcji «Opinie».

Format linku:

https://search.google.com/local/writereview?placeid=ChIJ...
https://g.page/r/XXXXXXXX/review
https://maps.app.goo.gl/XXXXX

Wszystkie trzy formaty działają.

Dlaczego Aktywność klientów pokazuje zera?

Śledzenie zdarzeń (landing_open / google_click) zaczęło działać po ostatniej aktualizacji. Jeśli strona lądowania nie była jeszcze otwierana z nową wersją — danych jeszcze nie ma. Statystyki zbiorą się automatycznie.

Jedno otwarcie liczone jest kilka razy?

Nie. Działa deduplikacja: jeśli z tego samego urządzenia strona jest otwarta ponownie w ciągu 30 sekund — drugie otwarcie nie jest rejestrowane. To zabezpieczenie przed podwójnym liczeniem przy inicjalizacji Blazora.

Czy można zmienić slug (adres URL strony)?

Tak. Slug zmieniany jest przez administratora w /admin/edit/{slug}. Uwaga: po zmianie sluga stare kody QR przestają działać — trzeba wydrukować nowe materiały fizyczne.

Jak podłączyć konto Google do istniejącego konta?

Zaloguj się przez /login/legacy przez stary username/hasło
W pulpicie kliknij przycisk Connect w niebieskiej planszy
Zaloguj się przez Google
Gotowe — wszystkie dane zachowane, kolejne logowanie przez Google

Maksymalny rozmiar przesyłanych plików?

Logo i zdjęcie tła — maksymalnie 5 MB każde. Obsługiwane formaty: PNG, JPG, WebP, GIF.

Gdzie przechowywane są obrazy?

W osobnym magazynie plików (MinIO) na serwerze — pliki są niezależne od bazy danych i nie giną przy aktualizacjach. Przeglądarka nigdy nie odwołuje się do magazynu bezpośrednio — wszystkie żądania są proksowane przez /logo/{key} endpoint aplikacji.

Dokumentacja Avelis