Format łańcucha UserAgent na potrzeby badań firmy Gemius

Format łańcucha UserAgent
na potrzeby badań firmy Gemius
Dokument przygotowany przez:
Zespół Megapanel Polska
Aktualizacja:
10 marca 2014
Zawartość dokumentu:
Informacje ogólne .............................................................................................................................................. 1
Zawartość i struktura Pola User Agent ............................................................................................................... 2
Aplikacje PC – dodatkowe uzupełnianie UA o informacje z rejestru Windows ................................................. 3
Rozdzielanie znakiem spacji ............................................................................................................................... 3
Aplikacje mobilne - dodatkowe biblioteki .......................................................................................................... 4
Pomoc techniczna .............................................................................................................................................. 4
Postępu 18 B Street, Orion building, IX floor, 02-676 Warsaw, tel. (0 22) 390 90 90, fax. (0 22) 874 41 01
Informacje ogólne
UserAgent jest to nagłówek wysyłany podczas komunikacji z serwerem WWW (następującej np.
w trakcie przeglądania stron www przez internautę). Nagłówek służy serwisom internetowym (np. aplikacji
napisanej w języku PHP) do rozpoznania typu programu klienckiego, jak również do budowania statystyk
odwiedzin witryn WWW (źródło: Wikipedia).
Po rozkodowaniu tego pola Gemius określa np. systemy operacyjne lub typy urządzeń, z których
pochodzi ruch na danym serwisie czy aplikacji, co umożliwia późniejsze grupowanie danych wg tych
wymiarów. Dlatego niezwykle ważne jest, aby twórcy witryn i aplikacji, którzy chcą, aby ich witryna czy
aplikacja była obejmowana badaniami Gemiusa, wdrożyli poniższe zalecenia dotyczące konstrukcji pola
UserAgent.
Przeglądarki internetowe
Przegladarki internetowe nadają UserAgent samodzielnie, wg określonych reguł, dlatego w tym
wypadku nie ma potrzeby ingerowania w to przez twórców witryn.
Aplikacje
W przeciwieństwie do przeglądarek, aplikacje mogą wpływać na kształt łańcucha UserAgent
wysyłanego przez skrypty Gemius umieszczone w danej aplikacji. Stąd potrzeba ustandaryzowania tego
wpisu w przypadku aplikacji.
Właściciele aplikacji, którzy chcą aby ich aplikacje były widoczne w badaniach Gemius, w tym na
przykład:

były objęte audytem w badaniu Megapanel PBI/Gemius lub aby materiały audio lub wideo
emitowane w aplikacji mogły być prezentowane w badaniu Megapanel PBI/Gemius
(w sekcji „Stream”)

były dostosowane do adserwera AdOcean

były odpowiednio klasyfikowane w badaniach gemiusTraffic i gemiusPrism
zobowiązani są do umieszczenia skryptów audytowych w aplikacji oraz zachowania poniżej opisanego
formatu łańcucha UserAgent w procesie przesyłania danych przez skrypty (w tym skrypty audytowe).
Dotyczy to zarówno przypadków, w których wysyłanie danych do systemu firmy badawczej następuje
bezpośrednio przez aplikację (bez pośrednictwa wbudowanej do aplikacji przeglądarki www), jak
i przypadków, w których następuje to za pośrednictwem wbudowanej do aplikacji przeglądarki www (w tym
przypadku wbudowana przeglądarka powinna przesyłać w polu User Agent informacje określone poniżej,
w tym informacje o nazwie i wersji aplikacji).
Aplikacjami (w rozumieniu tego dokumentu) nie są aplikacje, które działają w ramach innych
aplikacji lub witryn (np. działające jako dodatek w ramach komunikatora GG, wtyczek i dodatków
do przeglądarek, aplikacji na facebook.com itp.) ani aplety umieszczone na stronach www. Aplety, które
Strona 1 z 4
Postępu 18 B Street, Orion building, IX floor, 02-676 Warsaw, tel. (0 22) 390 90 90, fax. (0 22) 874 41 01
zostały oskryptowane np. skryptami do pomiaru stream, powinny przesyłać taki sam, niezmodyfikowany
User Agent, jaki przesyła strona www, na której są umieszczone. Tego typu aplety powinny też przesyłać –
w przeznaczonych do tego polach - pełny url strony, na której aplet został wywołany, wraz z refererem.
Przesłanie pola UserAgent w formacie odmiennym od opisanego w dokumencie daje firmie
badawczej podstawę np. do nieuwzględnienia danej aplikacji jako audytowanej w wynikach badania
Megapanel PBI/Gemius za miesiąc, w którym rozbieżności wystąpiły.
Zawartość i struktura Pola User Agent
Format łańcucha User-Agent jest określony w sekcji 14.43 dokumentu RFC 2616 (HTTP/1.1)
(http://tools.ietf.org/html/rfc2616#section-14.43).
Zawartość łańcucha User-Agent podzielona jest na sekcje opisujące dany produkt (np. przeglądarka, system
operacyjny, urządzenie). W celu zminimalizowania prawdopodobieństwa błędnej identyfikacji, firma
badawcza zaleca ustaloną, opisaną kolejność zapisu zawartości łańcucha UserAgent. Błędna kolejność
zapisu nie stanowi podstawy do wykluczenia danej aplikacji z audytu badania Megapanel PBI/Gemius.
Gemius zaleca, aby zawartość i struktura UserAgent aplikacji (zarówno mobilnych, jak i innych) była
następująca:
NazwaAplikacji/wersja (ModelUrządzenia; Oznaczenie_Wersji SystemOperacyjny) NazwaSilnika/wesja
(OpcjeSilnika)

Nazwa i wersja aplikacji (np. MojaAplikacja/5.0). Dopuszczane jest dodanie do nazwy aplikacji
jednego z trzech sufixów (końcówek) „_MOBILE”, „_TV” lub „_PC”, poprzedzone znakiem
podkreślenia „_” (np. MojaAplikacja_MOBILE/5.0, MojaAplikacja_TV/5.0, Moja Aplikacja_PC/5.0),
o ile są one zgodne z rzeczywistą platformą, na której operuje dana aplikacja. Pozostawienie nazwy
aplikacji bez sufixu także jest prawidłowe.

Nazwa modelu urządzenia i oznaczenia wersji (tylko w przypadku urządzeń innych niż komputer
stacjonarny lub laptop, czyli np. telefonów komórkowych, tabletów czy telewizorów) – wg tego pola
Gemius może odróżnić ruch mobilny od niemobilnego oraz wyodrębnić grupy urządzeń (np. tablety,
telewizory, itd.). Aplikacja powinna nadawać taką nazwę, jaką nadałaby przeglądarka. Jeśli
przeglądarka zainstalowana na danym urządzeniu uzupełnia pole UserAgent o słowo „MOBILE” to
aplikacja dedykowana na to urządzenie również powinna dodawać to słowo do UserAgenta.

Oznaczenie systemu operacyjnego (np. Windows NT 6.1, Android) – aplikacja powinna nadawać
taką nazwę systemu operacyjnego, jaką nadałaby przeglądarka np. w przypadku systemu Windows
Strona 2 z 4
Postępu 18 B Street, Orion building, IX floor, 02-676 Warsaw, tel. (0 22) 390 90 90, fax. (0 22) 874 41 01
XP przeglądarka nadaje oznaczenie Windows NT 5.1. Pełna lista oznaczeń używanych przez systemy
Windows znajduje się na stronie http://msdn.microsoft.com/library/ms537503.aspx w sekcji:
Platform Tokens.

(Opcjonalnie) Nazwa silnika, na którym oparta jest aplikacja oraz jego wersja (tylko jeżeli aplikacja
jest oparta na znanym ogólnie, a nie stworzonym autorsko, silniku) np. (Gecko/1.0)
Aplikacje PC – dodatkowe uzupełnianie UA o informacje z rejestru Windows
W przypadku aplikacji działających na PC pod systemem Windows, w polu UserAgent dodatkowo powinna
być sprawdzana (regularnie, przy każdym hicie) i wysyłana (z każdym hitem, czyli informacją wysyłaną przez
skrypty audytowe do hitkollektorów Gemius) informacja pobrana z rejestru Windows, znajdująca się pod
kluczem HKEY_CURRENT_USER\Software\NetPanel\UserAgent.

W przypadku braku tego wpisu w rejestrze nie ma potrzeby doklejania go do pola UserAgent.
Aplikacja regularnie, przy każdym hicie, powinna sprawdzać obecność tego wpisu w rejestrze
i w razie jego pojawienia się – doklejać go do pola UserAgent.

W przypadku istnienia tego wpisu aplikacja powinna regularnie (przy wysyłaniu każdego hitu)
sprawdzać aktualną zawartość wyżej wymienionego pola rejestru i taki aktualny stan wpisywać do
pola UserAgent. W przypadku zmiany zawartości tego pola rejestru, w polu UserAgent powinno
nastąpić nadpisanie poprzedniego wpisu nowym wpisem tak, aby nie wystąpiła sytuacja, w której
w polu UserAgent znajduje się jednocześnie kilka wpisów z rejestru, pochodzących z różnych
momentów czasowych. W polu UserAgent powinna znajdować się jedynie aktualna zawartość
wskazanego pola rejestru.
Rozdzielanie znakiem spacji
Do oddzielania poszczególnych sekcji UserAgent powinien być używany znak spacji. Ważne jest, aby spacji
nie zastępować innymi znakami, np. przecinkiem. Inne znaki mogą współwystępować, ale spacja ma być
znakiem rozdzielającym pola. Brak rozdzielania spacjami sekcji UserAgent będzie skutkować brakiem
prawidłowego rozpoznania pól UserAgenta przez Gemius, a w konsekwencji nieprawidłową klasyfikacją
ruchu. Błędnie przekazane dane, uniemożliwiające poprawną identyfikację bez ponoszenia przez firmę
badawczą dodatkowych kosztów, stanowią podstawę do wykluczenia danej aplikacji np. z audytu w badaniu
Megapanel PBI/Gemius do czasu usunięcia błędu w aplikacji.
Przykład pola UserAgent wysyłanego przez aplikację mobilną - pole zawiera wszystkie z wyżej
wymienionych elementów:
IPLA/1.0 (iPhone; CPU iPhone OS 4_0 like Mac OS X) AppleWebKit/532.9 (KHTML, like Gecko)
Strona 3 z 4
Postępu 18 B Street, Orion building, IX floor, 02-676 Warsaw, tel. (0 22) 390 90 90, fax. (0 22) 874 41 01
Przykład pola UserAgent wysyłanego przez aplikacje na PC:
IPLA/5.0 (Windows NT 5.1) Gecko/20100101 43E1E83A-D6D5-CA9D-0021-CA187054F3B7
Aplikacje mobilne - dodatkowe biblioteki
Dodatkowe biblioteki, oferowane przez Gemius do pomiaru aplikacji mobilnych, nadają UserAgent
w postaci rozpoznawanej przez Gemius, zatem w przypadku wykorzystania do oskryptowania aplikacji
mobilnych tych bibliotek nie ma potrzeby dodatkowej modyfikacji pola UserAgent. Te biblioteki to:

Mobile Plugin Android Package

Mobile Plugin iOS Package (support for 32-bits applications)

Mobile Plugin iOS 7 up to version 7.8 Package (support iPhone 3s and newer and 64-bits applications)

Mobile Plugin Windows Phone 7 Package

Mobile Plugin Windows Phone 8 Package
Pomoc techniczna
W przypadku wątpliwości lub w celu weryfikacji, czy ustawiony UA jest poprawnie rozpoznawany, można
skontaktować się z Działem Wsparcia Technicznego ([email protected]), który przeprowadzi analizę UA
i sposobu jego klasyfikacji.
W przypadku błędnego rozpoznania, osoba odpowiedzialna dokona
odpowiednich zmian w systemie rozpoznawania bądź przekaże sugestię, które elementy UA powinny zostać
zmienione.
Podsumowanie
Gemius zaleca zastosowanie opisanej wyżej zawartości i struktury pola UserAgent, co umożliwi prawidłowe
rozpoznawanie żródła ruchu i przypisywanie go do odpowiednich kategorii w badaniach firmy Gemius (np.
jako ruch z urzadzeń mobilnych). Błędnie przekazane dane uniemożliwiają poprawną identyfikację
i stanowią podstawę do wykluczenia danej aplikacji np. z audytu w badaniu Megapanel PBI/Gemius.
Strona 4 z 4
Postępu 18 B Street, Orion building, IX floor, 02-676 Warsaw, tel. (0 22) 390 90 90, fax. (0 22) 874 41 01