Format łańcucha UserAgent dla aplikacji

Format łańcucha UserAgent dla aplikacji

Format łańcucha UserAgent
na potrzeby badań firmy Gemius
str. 1
Spis treści:
Informacje ogólne ....................................................................................................................................... 3
Zawartość i struktura Pola User Agent ................................................................................................ 4
Aplikacje PC – dodatkowe uzupełnianie UA o informacje z rejestru Windows .................... 6
Rozdzielanie znakiem spacji .................................................................................................................... 6
Aplikacje mobilne - dodatkowe biblioteki ........................................................................................... 7
Pomoc techniczna ........................................................................................................................................ 7
str. 2
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
Przeglądarki 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 do serwerów firmy Gemius. 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 Gemius/PBI lub aby materiały audio lub
wideo emitowane w aplikacji mogły być prezentowane w badaniu
Gemius/PBI

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
str. 3
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
, wtyczek i dodatków do przeglądarek, aplikacji na facebook.com itp.) ani aplety
umieszczone na stronach www. Aplety, które 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 Gemius/PBI 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 w badaniu Gemius/PBI.
Gemius zaleca, aby zawartość i struktura UserAgent aplikacji (zarówno mobilnych, jak
i innych) była następująca:
NazwaAplikacji/wersja
gAppTag
(ModelUrządzenia;
Oznaczenie_Wersji
SystemOperacyjny) NazwaSilnika/wesja (OpcjeSilnika) EmbeddedBrowser DeviceUID
str. 4

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.

gAppTag (tylko dla danych z aplikacji a nie WWW)
Ciąg znaków który ma być obowiązkowo dodawany tylko w przypadku danych z
aplikacji – służy do odróżniania ruchu z aplikacji od ruchu ze stron WWWw
przypadku ruchu ze stron WWW.

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 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)

EmbeddedBrowser (dodawane obowiązkowo ale wyłącznie przy hitach
wysyłanych z przeglądarki wbudowanej w aplikację np. webview)
Poza dostarczaniem informacji że jest to hit z takiej przeglądarki oznaczenie
EmbeddedBrowser gwarantuje, że w aplikacji nie będą emitowane
kwestionariusze rekrutacyjne do badania podczas przeglądania stron
internetowych w aplikacji.

DeviceUID – dodawany ma być na końcu w przypadku skryptowania aplikacji
mobilnych. Ma tam być umieszczany identyfikator Advertising ID (AAID czyli
str. 5
Google’s Advertising ID) w przypadku Androida, IDFA (Identifier for
Advertising) w przypadku iOS.
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 Gemius/PBI do czasu usunięcia
błędu w aplikacji.
str. 6
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)
Przykład pola UserAgent wysyłanego przez aplikacje na PC:
IPLA/5.0 (Windows NT 5.1) Gecko/20100101 43E1E83A-D6D5-CA9D-0021CA187054F3B7
Aplikacje mobilne - dodatkowe biblioteki (SDK)
Dodatkowe biblioteki SDK, 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. Przykładowe postacie userAgenta wysyłanego
przez SDK:
Na systemie Android:
GemiusSDK/1.2 (Linux; Android 5.1.1; hi6210sft Build/LMY47X)
AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/39.0.0.0
Mobile Safari/537.36 DeviceUID: 42b19a5f-0f8b-47c2-b480-0d156fe334de
Na systemie iOS:
GemiusSDK/1.2.1 (iPad; CPU OS 9_3_2 like Mac OS X) AppleWebKit/601.1.46
(KHTML, like Gecko) Mobile/13F69 DeviceUID:
C5077EDD-6021-48C6-9E0B-D31AB3DE1D66
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
str. 7
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 urządzeń mobilnych). Błędnie
przekazane
dane
uniemożliwiają
poprawną
identyfikację
i
stanowią
do wykluczenia danej aplikacji np. z audytu w badaniu Gemius/PBI.
str. 8
podstawę