Przewodnik po API analityki witryny dla JSON i CSV

Czym jest API analityki internetowej

API analityki internetowej to bezpośredni sposób na zapytanie systemu analitycznego o dane. Zamiast otwierać pulpit nawigacyjny i klikać przez wykresy, twoja aplikacja wysyła żądanie i otrzymuje uporządkowane liczby z powrotem. To ma znaczenie w poniedziałkowy poranek, szczególnie gdy 12 raportów potrzebuje tych samych danych o ruchu.

Pulpit nawigacyjny jest stworzony dla ludzi. API analityki jest stworzone dla systemów. Pulpit pomaga marketerowi sprawdzić, czy ruch organiczny wzrósł po kampanii; API analityki pozwala skryptowi pobierać te same dane o ruchu codziennie o 7:00 i umieszczać je w raporcie bez potrzeby ręcznego kopiowania komórek.

Większość API analityki udostępnia dane o odsłonach, sesjach, zdarzeniach, źródłach ruchu, konwersjach i zakresach czasowych. Niektóre zwracają również typ urządzenia, kraj, strony docelowe lub tagi kampanii. Dobre API utrzymuje przewidywalną strukturę, co jest powodem, dla którego programiści je lubią i dlaczego zespoły przestają się spierać, która wyeksportowana tabela była „najświeższa”.

Ręczne raportowanie wciąż działa w przypadku małych zadań. Jeśli potrzebujesz jednego zrzutu ekranu z zeszłego tygodnia, eksport z pulpitu może być wystarczający. Jeśli potrzebujesz 90 dni danych dla pięciu witryn i cyklicznego raportu, API będzie lepszym rozwiązaniem. Dla zespołów korzystających z Astrina, zaleta jest prosta: mniej poszukiwań kart, mniej błędów przy kopiowaniu i wklejaniu oraz jedno miejsce do utrzymania przepływu danych.

Kluczowe dane, które możesz pobrać z API analityki internetowej

Większość odpowiedzi API analityki stron internetowych zaczyna się od wyświetleń stron i sesji. Wyświetlenia stron pokazują, ile stron zostało załadowanych; sesje grupują wizyty w kawałki aktywności. Strona z 4 000 wyświetleniami stron i 1 200 sesjami może mieć powtarzających się czytelników z mniejszej publiczności, co jest rodzajem wskazówki, którą rzeczywiście wykorzystuje redaktor treści.

Następnie są źródła ruchu. API analityki często klasyfikuje ruch jako organiczne wyszukiwanie, płatne wyszukiwanie, bezpośrednie, polecenia, e-mail lub media społecznościowe. To podział odpowiada na praktyczne pytania. Jeśli 60% sesji pochodzi z linków polecających po kampanii partnerskiej, możesz zobaczyć, czy ta kampania zasługuje na kolejny miesiąc.

Wydarzenia i konwersje mają znaczenie, ponieważ pokazują działania, a nie tylko wizyty. Wydarzeniem może być kliknięcie przycisku, otwarcie formularza lub odtworzenie wideo. Konwersją może być rejestracja, zakup lub przesłanie leadu. Jeden mały szczegół: jeśli wskaźnik konwersji formularza spadnie po edycji strony docelowej, API analityki podaje datę i stronę, więc nie musisz zgadywać.

Raporty oparte na czasie są często najłatwiejsze do odczytania i najłatwiejsze do niewłaściwego użycia. Dane dzienne mogą pokazywać skoki po wysłaniu newslettera, podczas gdy dane tygodniowe wygładzają szumy. Raporty miesięczne pomagają, gdy zespół chce linii trendów, ale mogą ukrywać dzień, w którym błąd przerwał śledzenie mobilne na 18 godzin.

Niektóre interfejsy API analityki udostępniają również pola na poziomie treści, takie jak najpopularniejsze strony, strony wyjścia i strony docelowe. Są one przydatne dla zespołów redakcyjnych i pracy SEO. Strona z dużym ruchem i wysokim wskaźnikiem wyjść może wymagać silniejszej ścieżki linków wewnętrznych, a strona docelowa z dużą liczbą sesji, ale słabymi konwersjami może potrzebować jaśniejszego formularza lub oferty.

Dla zespołów porównujących wydajność witryn w różnych lokalizacjach, interfejs API analityki może pomóc w ustandaryzowaniu tych samych pól danych w każdej witrynie. Jeśli już śledzisz wiele witryn w Astrina, ta spójność staje się mniej teoretyczna, a bardziej jak codzienny nawyk. Jeden schemat. Jedna zasada nazewnictwa. Mniej zamieszania.

Wyjście API JSON: Jak są zorganizowane dane

JSON jest powszechnym formatem dla wyjścia interfejsu API analityki, ponieważ dobrze pasuje do nowoczesnych aplikacji. Jest czytelny dla maszyn, dość czytelny dla ludzi i wystarczająco elastyczny, aby pomieścić listę raportów lub podsumowanie pojedynczej metryki. Ta elastyczność ma znaczenie, gdy odpowiedź zawiera zarówno sumy, jak i podziały dzienne w tym samym wywołaniu.

Typowa odpowiedź JSON używa par klucz-wartość. Klucz może być sessions a wartość może wynosić 1,284. Inny klucz może być traffic_sources, który może zawierać tablicę obiektów. Każdy obiekt może zawierać nazwę źródła, liczbę sesji i liczbę konwersji. Taki zagnieżdżony kształt pozwala jednej odpowiedzi przenieść wystarczająco dużo szczegółów dla pulpitu nawigacyjnego i wykresu.

Oto część, która interesuje programistów: tablice zazwyczaj przechowują powtarzające się elementy, a obiekty zazwyczaj przechowują powiązane pola. Codzienny raport może zwrócić tablicę 30 obiektów, po jednym na każdy dzień. Każdy obiekt może zawierać date, pageviews, i conversions. Aplikacja frontendowa może przejść przez te 30 elementów i narysować wykres liniowy bez dodatkowego czyszczenia.

JSON wspiera również zagnieżdżanie, gdy API analityczne musi pokazać hierarchię. Na przykład, odpowiedź może zawierać obiekt najwyższego poziomu summary i tablicę series poniżej. Ułatwia to oddzielenie sum od danych trendowych, co jest przydatne, gdy analityk chce uzyskać całkowitą liczbę sesji i codzienny wzór w jednym żądaniu.

Parsowanie JSON jest zazwyczaj proste w JavaScript, Pythonie, PHP lub Go. Aplikacja wysyła żądanie, otrzymuje tekst, konwertuje go na natywną strukturę danych i odczytuje potrzebne pola. Programista może następnie przechować odpowiedź, porównać ją z poprzednim uruchomieniem lub wprowadzić do widoku raportu. Jeśli jedno pole jest brakujące, to brakujące pole powinno być obsługiwane w sposób jawny, a nie ignorowane. Ciche błędy stają się głośne później.

JSON nie jest doskonały. Bardzo duże odpowiedzi mogą stać się ciężkie, a zagnieżdżone struktury mogą być niewygodne dla arkuszy kalkulacyjnych. Mimo to, dla API analitycznego, JSON jest domyślnym wyborem z jakiegoś powodu: dobrze się przemieszcza, dobrze skaluje i pasuje do sposobu, w jaki oprogramowanie już działa.

Eksport CSV: Kiedy płaski plik jest lepszym wyborem

CSV to prosty format plików, któremu wiele zespołów wciąż ufa. To tylko wiersze i kolumny, co ułatwia otwieranie w Excelu, Google Sheets, LibreOffice lub narzędziu BI. Jeśli lider marketingu chce posortować 500 wierszy danych kampanii przed spotkaniem o 14:00, CSV często jest szybsze niż tworzenie nowej integracji.

CSV jest szczególnie przydatne do analizy offline. Zespół finansowy może chcieć pobrać miesięczny eksport, zarchiwizować go i porównać z notatkami o przychodach. Zespół treści może chcieć połączyć plik CSV z kalendarzem redakcyjnym. Człowiek może w kilka sekund przejrzeć plik CSV i dostrzec dziwne liczby, takie jak dzień z 0 sesjami i 300 konwersjami.

Wymiana to struktura. CSV jest płaskie, więc nie radzi sobie dobrze z zagnieżdżonymi relacjami. Jeśli Twoje API analityczne zwraca źródła ruchu, segmenty urządzeń i ścieżki konwersji, CSV może zmusić te punkty danych do oddzielnych plików lub dodatkowych kolumn. To jest do zarządzania, ale jest niezdarne, gdy raport zmienia się co kwartał.

CSV jest również mniej przyjazne dla automatyzacji niż JSON, gdy model danych jest złożony. Pipeline może łatwo odczytać CSV, tak, ale często wymaga więcej oczyszczenia: sprawdzania separatorów, walidacji nagłówków, obsługi pustych komórek i analizy dat. Jeśli potrzebujesz tylko cotygodniowego eksportu z 20 kolumnami, to w porządku. Jeśli potrzebujesz warstwowego raportu z 8 wymiarami, JSON zazwyczaj lepiej pasuje.

Dla narzędzi BI, CSV może wciąż być najprostszym mostem. Zespoły często eksportują plik, ładują go do Power BI lub Looker Studio, a następnie porównują go z innym źródłem. Kluczową decyzją nie jest to, czy CSV jest przestarzałe. Kluczową decyzją jest to, czy płaski plik jest wystarczający dla zadawanych pytań.

Jak uwierzytelnić i wysłać żądania API

Większość interfejsów API analitycznych używa jednej z trzech metod uwierzytelniania: kluczy API, tokenów dostępu lub OAuth. Klucz API jest najprostszy. Token jest lepszy, gdy dostęp musi wygasnąć lub być rotowany. OAuth jest przydatny, gdy użytkownik musi przyznać dostęp bez dzielenia się hasłem. Każda metoda ma inny kompromis i każda z nich wymaga starannego przechowywania.

Przepływ żądania jest zazwyczaj prosty. Po pierwsze, aplikacja przechowuje dane uwierzytelniające w bezpiecznym miejscu. Po drugie, wysyła żądanie do punktu końcowego API analitycznego. Po trzecie, punkt końcowy sprawdza uprawnienia i zwraca dane, jeśli żądanie jest ważne. Jeśli żądanie jest błędne, API zwraca kod błędu i zazwyczaj wiadomość wyjaśniającą, co się nie powiodło. Tę wiadomość należy traktować poważnie.

Bezpieczeństwo ma znaczenie, ponieważ dane analityczne to nie tylko liczby ruchu. Mogą ujawniać wyniki kampanii, zachowania klientów i wolumen leadów. Trzymaj dane uwierzytelniające z dala od kodu front-end. Rotuj klucze, gdy zmienia się personel. Ustaw uprawnienia tak, aby token tylko odczytywał strony lub raporty, których potrzebuje. Jeśli API analityczne oferuje dostęp z ograniczeniami, użyj go.

Praktyczna prośba często zawiera identyfikator witryny, zakres dat i listę metryk. Programista może poprosić o sesje i konwersje od 1 marca do 31 marca, a następnie powtórzyć to samo zapytanie dla kwietnia. Taki wzór jest powszechny, ponieważ utrzymuje porównania w czystości. Ułatwia to również zaplanowane synchronizacje, dlatego wiele zespołów łączy dostęp do API analityki z narzędziami takimi jak API dewelopera — Astrina gdy chcą mieć wszystkie dane swojej witryny w jednym miejscu.

Obsługa błędów powinna znajdować się w pierwszym szkicu, a nie w ostatnim. Błąd 401 zazwyczaj oznacza, że token nie powiódł się. Błąd 429 często oznacza ograniczenie liczby żądań. Błąd 500 wskazuje na problem z serwerem. Każdy z nich powinien wywołać konkretną reakcję w twojej aplikacji, a nie ogólną pętlę ponownych prób, która bez powodu wciąż atakuje punkt końcowy.

Typowe przypadki użycia API analityki witryny

Niestandardowe pulpity nawigacyjne to jedno z najczęstszych zastosowań. Zespół może chcieć pulpitu, który pokazuje tylko 6 metryk, które sprawdzają codziennie: sesje, konwersje, najlepsze źródło, najlepsza strona docelowa, trend odrzuceń i powiązanie przychodów. API analityki umożliwia to bez zmuszania wszystkich do klikania przez ogólny interfejs.

Automatyczne raportowanie to kolejny silny przypadek użycia. Skrypt może pobierać dane z zeszłego tygodnia w każdy poniedziałek, wypełniać szablon i wysyłać go do interesariuszy o 8:30. To oszczędza czas, tak, ale także utrzymuje spójny format. Ludzie przestają pytać, skąd pochodzą liczby, ponieważ te same liczby przychodzą w tym samym układzie co tydzień.

Magazynowanie danych jest przydatne, gdy dane analityczne muszą być obok danych CRM, wydatków na reklamy lub danych o produktach. Magazyn może przechowywać 2 lata aktywności na stronie obok rekordów sprzedaży, co ułatwia odpowiadanie na pytania o atrybucję. Jeśli płatne wyszukiwanie wygenerowało 300 sesji i 24 leady w jeden dzień, magazyn może pomóc połączyć ten ruch z późniejszymi przychodami.

Atrybucja marketingowa to miejsce, w którym API analityczne zaczyna przynosić korzyści. Kampania może dotknąć e-maila, wyszukiwania organicznego i bezpośredniej wizyty przed konwersją. Jeśli spojrzysz tylko na ostatni klik, przegapisz część ścieżki. Jeśli przechowujesz podstawowe dane analityczne, możesz porównywać wzorce pierwszego dotyku, ostatniego dotyku i wieloetapowe zamiast spierać się z pamięci.

Narzędzia wewnętrzne to cichszy, ale wartościowy przypadek użycia. Zespoły produktowe budują panele administracyjne. Zespoły wsparcia budują widoki kontekstu zgłoszeń. Redaktorzy budują tablice wyników treści. API analityczne może zasilać każde narzędzie tym samym źródłem prawdy, co redukuje znany problem „czyja tabela jest poprawna?”.

Najlepsze praktyki w pracy z danymi analitycznymi

Paginacja jest pierwsza, gdy zestaw odpowiedzi jest duży. Jeśli API analityczne zwraca 100 wierszy na raz, Twoja aplikacja powinna poprosić o następną stronę zamiast próbować pobrać wszystko za jednym razem. To ma znaczenie w przypadku długich zakresów czasowych, dużych witryn lub szczegółowych danych o zdarzeniach. Jedna pominięta strona może oznaczać jeden brakujący miesiąc.

Limity szybkości są kolejnym ograniczeniem. Jeśli API analityczne pozwala tylko na określoną liczbę żądań na minutę, zbuduj swoją pracę synchronizacyjną wokół tego limitu. Rozdzielaj wywołania. Pamiętaj odpowiedzi, gdy ten sam raport jest żądany wielokrotnie. Zespół, który ignoruje limity szybkości, często odkrywa je o 9:01, dokładnie wtedy, gdy odświeżanie raportu zaczyna zawodzić.

Filtrowanie dat utrzymuje dane w użyteczności. Zawsze pytaj o konkretny zakres, czy to wczoraj, ostatnie 7 dni, czy od stycznia do marca. Otwarte pobrania tworzą niespójne porównania i mogą sprawić, że ten sam raport będzie wyglądał inaczej we wtorek niż w piątek. To szybki sposób na utratę zaufania do liczb.

Dobre zarządzanie błędami powinno obejmować ponowne próby, ale nie ślepe ponowne próby. Spróbuj ponownie raz lub dwa razy w przypadku przejściowych błędów. Zatrzymaj się i powiadom, gdy dane uwierzytelniające zawiodą lub format żądania jest nieprawidłowy. Pipeline, który cicho pomija dzień danych analitycznych, może pozostawić raport kierownictwa błędnym przez tydzień. Ludzie zauważają tego rodzaju lukę.

Cache'owanie pomaga, gdy ten sam wskaźnik jest żądany przez wiele narzędzi. Jeśli Twój pulpit nawigacyjny i Twój cotygodniowy e-mail potrzebują tego samego 24-godzinnego podsumowania, zapisz odpowiedź na krótki czas zamiast pytać API analityczne dwa razy. To zmniejsza obciążenie i daje użytkownikom stabilniejszy widok. To także sprawia, że cały system jest mniej skoczny, gdy ruch wzrasta.

Prowadź rejestr zmian schematu. Jeśli API analityczne dodaje pole lub zmienia jego nazwę, Twój parser nie powinien się zepsuć bez ostrzeżenia. Tutaj logi zmian i testy przynoszą korzyści. Mały test w odniesieniu do wczorajszego ładunku może wychwycić złą nazwę pola, zanim raport zostanie opublikowany. Ten jeden test może zaoszczędzić godzinę sprzątania.

Wybór odpowiedniej metody dostępu dla Twojego zespołu

Dostęp do API działa najlepiej, gdy Twój zespół potrzebuje danych na żywo, zaplanowanych synchronizacji lub niestandardowych aplikacji. Odpowiedzi JSON API pasują do programistów, którzy chcą struktury i elastyczności. Eksport CSV pasuje do analityków, którzy chcą pliku, który mogą otworzyć, posortować i udostępnić bez budowania najpierw potoku. Odpowiedni wybór zależy od zadania, a nie od mody.

Jeśli Twój zespół jest mały, a raportowanie jest okazjonalne, CSV może być wystarczające. Jeśli Twój zespół ma programistę, hurtownię danych lub cykliczny raport, API analityczne zazwyczaj zwróci się szybciej. Jeśli zarządzasz kilkoma stronami i chcesz mieć jedno miejsce do ich sprawdzania, produkt taki jak Każda strona, którą się opiekujesz, w jednym pulpicie nawigacyjnym — Astrina może ułatwić śledzenie przepływu danych.

Odpowiedzi API JSON są najlepszym rozwiązaniem, gdy system musi odczytać i przekształcić dane. CSV jest lepszym rozwiązaniem, gdy osoba musi sprawdzić lub połączyć dane. Same API analityczne są transportem; JSON i CSV to formy, jakie dane mogą przyjąć w drodze na zewnątrz. Ta prosta różnica oszczędza wiele złych decyzji dotyczących konfiguracji.

Pomyśl o następnych 6 miesiącach, a nie tylko o następnym raporcie. Jeśli zespół planuje zbudować pulpit nawigacyjny, zsynchronizować z magazynem lub pobierać codzienne dane dla 3 stron, zacznij od API analitycznego. Jeśli zespół potrzebuje tylko kwartalnego eksportu do przeglądu, plik płaski może być wystarczający. W każdym przypadku cel jest ten sam: dostarczyć odpowiednie dane analityczne strony internetowej do odpowiednich rąk, nie zmuszając ludzi do ponownego wpisywania liczb z ekranu.