Obsługa administracyjna kont kontrolowanych przez użytkowników – przewodnik dla programistów korzystających z interfejsu API

W tym dokumencie omawiamy ważne pojęcia związane z używaniem interfejsu API do obsługi administracyjnej do tworzenia nowych kont Google Analytics.

Wstęp

Interfejs API do obsługi administracyjnej umożliwia tworzenie nowych kont Google Analytics i włączanie Google Analytics dla klientów na dużą skalę. Jest przeznaczona dla kwalifikujących się usługodawców i dużych partnerów. Wprowadzenie do interfejsu API do obsługi administracyjnej znajdziesz na stronie z omówieniem obsługi administracyjnej.

Zanim zaczniesz

Dostęp do wszystkich interfejsów API Google Analytics uzyskuje się w podobny sposób. Zanim zaczniesz korzystać z interfejsu API do obsługi administracyjnej, musisz wykonać te czynności:

  • Na stronie bibliotek klienta znajdziesz pełną listę bibliotek klienta dla poszczególnych języków programowania, które współpracują z interfejsem API.
  • Przeczytaj Przewodnik, aby poznać interfejs API i dowiedzieć się, jak uzyskać dostęp do danych bez użycia biblioteki klienta.

Każda biblioteka klienta zapewnia pojedynczy obiekt usługi analitycznej, by uzyskać dostęp do interfejsu API do obsługi administracyjnej. Aby utworzyć obiekt usługi, zazwyczaj musisz wykonać te czynności:

  1. Zarejestruj aplikację w Konsoli interfejsów API Google.
  2. Autoryzuj, aby utworzyć nowe konto Google Analytics.
  3. Utwórz obiekt usługi Analytics.

Jeśli nie udało Ci się wykonać tych czynności, zatrzymaj się i przeczytaj samouczek interfejsu Hello Google Analytics API. W tym samouczku omawiamy pierwsze kroki tworzenia aplikacji interfejsu Google Analytics API. Po ukończeniu kursu dowiesz się, jak uzyskać dostęp do interfejsów API Google Analytics w celu wykonywania codziennych zadań.

Przegląd

Podczas tworzenia kont Google Analytics za pomocą interfejsu API do obsługi administracyjnej musisz wziąć pod uwagę 2 oddzielne procesy:

  • Proces techniczny: kompleksowy proces automatycznego udostępniania konta Google Analytics użytkownikowi.
  • Przepływ użytkowników: kwestie dotyczące implementacji, które należy wziąć pod uwagę podczas tworzenia konta z perspektywy użytkownika.

W tym dokumencie opisujemy ogólne kroki i wymagania związane z każdym procesem.

Przebieg techniczny

Aby użyć interfejsu Provisioning API do utworzenia nowego konta i integracji z Google Analytics:

  1. Poproś użytkownika o uwierzytelnienie i autoryzację aplikacji lub usługi za pomocą protokołu OAuth 2.0.
  2. Utwórz zgłoszenie do konta za pomocą interfejsu API do obsługi administracyjnej.
  3. Przekieruj użytkownika, aby zaakceptował Warunki korzystania z usługi Google Analytics i zajął się odpowiedzią.
  4. (Opcjonalnie) Skonfiguruj konto i możliwości integracji.

Jeśli wykonasz wszystkie te czynności, zostanie dla niego utworzone konto Google Analytics, a uzyskasz identyfikator konta, identyfikator usługi i identyfikator widoku (profil) nowego konta.

W przypadku każdego z poniższych kroków znajdują się wymagania niezbędne do wykonania danego kroku, jego wyniki oraz opis procesu technicznego dotyczącego danego kroku.

1. Uwierzytelnianie i autoryzacja

Każdy użytkownik musi autoryzować Twoją aplikację i przyznać jej możliwość obsługi administracyjnej konta Google Analytics w jego imieniu. Zalecamy wykonanie tego kroku przy użyciu aplikacji Serwer WWW OAuth 2.0.

Co jest potrzebne, aby ukończyć ten krok

Rezultat tego kroku

Po zakończeniu procesu OAuth 2.0 użytkownik autoryzuje Twoją aplikację do obsługi administracyjnej konta w jego imieniu, a Ty otrzymasz token dostępu dla tego użytkownika.

Uwaga na temat tokenów i zakresów:

  • Jeśli po utworzeniu konta zamierzasz wysyłać dodatkowe żądania danych konfiguracji konta użytkownika lub danych do raportu, na tym etapie możesz też autoryzować dodatkowe zakresy. Mogą to być na przykład zakresy readonly lub edit.
  • Okres ważności tokenów dostępu jest ograniczony. Jeśli Twoja aplikacja wymaga dostępu do interfejsu Google Analytics API po zakończeniu okresu ważności pojedynczego tokena dostępu, możesz też poprosić o token odświeżania, ustawiając dla niego access_type=offline. Token odświeżania powinien być zapisany w bezpiecznej pamięci długoterminowej każdego użytkownika, ponieważ umożliwia on aplikacji uzyskiwanie nowych tokenów dostępu. Więcej informacji znajdziesz w sekcji Dostęp offline.

Techniczny przebieg tego kroku

Musisz uzyskać token dostępu dla użytkownika. Zgodnie z procedurą opisaną w dokumencie Serwer WWW OAuth 2.0 wyślij użytkownika do usługi Konta Google, a następnie przetwórz odpowiedź, gdy zostanie on przekierowany z powrotem do Twojej usługi po zakończeniu procesu uwierzytelniania.

Utwórz adres URL OAuth 2.0, który będzie odwiedzany

Gdy użytkownik kliknie przycisk lub link „Rozpocznij” lub „Utwórz konto”, powinien kierować na początek procesu OAuth 2.0, aby poprosić go o przyznanie uprawnień do obsługi administracyjnej. Na przykład:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Przetwórz odpowiedź z usługi Konta Google

Gdy użytkownik podejmie decyzję o przyznaniu dostępu do Twojej aplikacji, zostanie przekierowany do redirect_uri zgodnie z informacjami podanymi w utworzonym adresie URL za pomocą parametru zapytania zawierającego kod autoryzacji. Jeśli użytkownik zatwierdził żądanie, można użyć odpowiedzi z kodem autoryzacji do wymiany kodu autoryzacji na token dostępu, wysyłając żądanie POST do interfejsu Google Accounts API.

Zapisz token odświeżania (jeśli jest dostępny).

Token dostępu zostanie użyty w następnym kroku, aby umożliwić Ci tymczasowe jego przechowywanie. Jeśli prosisz też użytkownika o token odświeżania, przechowuj go w bezpiecznym miejscu, by używać go przez dłuższy czas. Token odświeżania ma długi czas ważności i można go używać do wystawiania nowych tokenów dostępu.

2. Tworzenie zgłoszenia do konta za pomocą interfejsu API do obsługi administracyjnej

Po otrzymaniu tokena dostępu dla autoryzowanego użytkownika możesz go użyć, aby wysłać do interfejsu API do obsługi administracyjnej żądanie utworzenia zgłoszenia do konta dla tego użytkownika. Bilet na konto jest pierwszym krokiem do utworzenia konta dla użytkownika.

Co jest potrzebne, aby ukończyć ten krok

Token dostępu dla autoryzowanego użytkownika zgodnie z opisem w sekcji Uwierzytelnianie i autoryzacja oraz te informacje dotyczące obsługi administracyjnej:

  • Identyfikator URI przekierowania
    • Określa, gdzie użytkownik jest przekierowywany po stronie Warunków korzystania z usługi Google Analytics. Może on być inny niż identyfikator URI przekierowania określony podczas procesu autoryzacji OAuth 2.0.
    • Wartość parametru URI przekierowania musi być dokładnie taka sama jak jedna z wartości zarejestrowanych w Google Developers Console (łącznie ze schematami http lub https, wielkością liter, znakiem „/”) na końcu.
  • Pola konta
    • Usługa name jest wymagana na koncie.
  • Pola usługi internetowej
    • Właściwość name jest wymagana dla tej usługi.
    • Identyfikator websiteUrl jest wymagany.
  • Pola profilu
    • Właściwość name jest wymagana dla profilu.
    • Opcjonalnie możesz podać wartość timezone. Wartość domyślna to America/Los_Angeles.

Podczas tworzenia zgłoszenia na koncie można ustawić tylko podstawowe pola wskazane powyżej. Po utworzeniu konta wszelkie dodatkowe zmiany w konfiguracji usługi lub widoku (profilu) możesz wprowadzać za pomocą interfejsu Management API.

Więcej informacji o tych polach znajdziesz w dokumentacji interfejsów API dotyczących kont, usług i widoków danych (profile).

Rezultat tego kroku

Po wysłaniu żądania do interfejsu API do obsługi administracyjnej przez krótki czas będzie dostępny dla użytkownika raport o koncie. Identyfikator zgłoszenia na koncie jest używany w ostatnim kroku do zachęcenia użytkownika do zaakceptowania Warunków korzystania z usługi i aktywowania konta. Konta nie można używać przed zaakceptowaniem Warunków korzystania z usługi.

Techniczny przebieg tego kroku

Przy użyciu tokena dostępu użytkownika, który został uzyskany podczas uwierzytelniania i autoryzacji, do interfejsu API do obsługi administracyjnej wysyłane jest żądanie HTTP POST.

Żądanie utworzenia zgłoszenia do interfejsu API do obsługi administracyjnej

Zapoznaj się z metodą createAccountTicket w dokumentacji interfejsu API do obsługi administracyjnej, aby dowiedzieć się, jak wysłać żądanie.

Odpowiedź z interfejsu API do obsługi administracyjnej

Żądanie zakończone powodzeniem zwraca odpowiedź 200. Treść odpowiedzi zawiera bilet na konto, który jest ważny. Zgłoszenie konta składa się z identyfikatora i szczegółów nowego drzewa konta.

Aby dowiedzieć się więcej o odpowiedzi, zapoznaj się z sekcją Account Ticket resource w dokumentacji interfejsu API do obsługi administracyjnej.

Odpowiedzi na błędy również muszą być obsługiwane przez aplikację.

3. Użytkownik akceptuje Warunki korzystania z usługi Google Analytics

Gdy uzyskasz identyfikator zgłoszenia dotyczącego konta dla użytkownika, możesz go użyć w prośbie o zaakceptowanie Warunków korzystania z usługi Google Analytics.

Co jest potrzebne, aby ukończyć ten krok

Identyfikator zgłoszenia do konta autoryzowanego użytkownika.

Rezultat tego kroku

Po ukończeniu procesu korzystania z usługi za pomocą identyfikatora zgłoszenia na koncie zostanie utworzone konto, usługa oraz widok (profil). Użytkownik będzie miał teraz aktywne konto. Odpowiedź ze strony warunków korzystania z usługi będzie zawierać identyfikator konta, identyfikator usługi oraz identyfikator widoku (profilu).

Techniczny przebieg tego kroku

Za pomocą identyfikatora zgłoszenia na koncie przekieruj użytkownika na stronę Warunków korzystania z usługi Google Analytics, na której może zaakceptować warunki, a potem musisz przetworzyć odpowiedź z interfejsu API.

Utwórz adres URL Warunków korzystania z usługi, który użytkownik ma odwiedzić

Przekieruj użytkownika na stronę Warunków korzystania z usługi i dołącz identyfikator zgłoszenia do konta jako część adresu URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Obsługa odpowiedzi dotyczącej Warunków korzystania z usługi

Gdy użytkownik wykona pewne czynności na stronie Warunków korzystania z usługi, zostanie przekierowany z powrotem do usługi redirectUri podanej podczas tworzenia zgłoszenia na koncie. Odpowiedź ze strony warunków korzystania z usługi zostanie dołączona jako część ciągu zapytania.

Odpowiedzi pomyślne zwrócą dane o nowo utworzonej strukturze konta, a także o pierwotnej wartości (accountTicketId):

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Jeśli na przykład moduł obsługi warunków korzystania z usługi dla Twojej aplikacji ma ustawienie http://www.your-app.com/gaTOS, podczas tworzenia zgłoszeń na koncie należy ustawić go jako redirectUri. Moduł obsługi warunków korzystania z aplikacji powinien oczekiwać i prawidłowo obsługiwać żądania HTTP GET, które zawierają parametry zapytania accountId, webPropertyId, profileId i accountTicketId w przypadkach, gdy zgłoszenie dotyczące konta jest prawidłowe, a użytkownik zaakceptował Warunki korzystania z usługi.

Nieudane odpowiedzi będą zawierały odpowiedź błędu:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Moduł obsługi warunków korzystania z usługi powinien też prawidłowo obsługiwać żądania HTTP GET, które zawierają parametr zapytania error, co wskazuje, że coś poszło nie tak. Wartość parametru zapytania może posłużyć do podjęcia dalszych działań lub wyświetlenia wiadomości użytkownikowi:

  • error=user_cancel – użytkownik nie zaakceptował warunków korzystania z usługi.
  • error=max_accounts_reached – użytkownik osiągnął limit konta Google Analytics.
  • error=backend_error – błąd ogólny. Serwer zwrócił błąd, który nie należy do żadnej z powyższych kategorii.

4. (Opcjonalnie) Możliwości integracji

Jeśli wykonasz czynności opisane powyżej w kroku technicznym, utworzysz konto dla użytkownika i będziesz mieć identyfikator konta, identyfikator usługi oraz identyfikator widoku (profilu). Jeśli żądasz też dodatkowych uprawnień, możesz też mieć token odświeżania dla użytkownika. Dzięki tym danym:

  • W razie potrzeby automatycznie wstaw standardowy fragment kodu śledzenia Google Analytics z identyfikatorem usługi nowo utworzonego konta na każdej stronie w witrynie użytkownika.
  • automatycznie skonfigurować właściwość użytkownika za pomocą interfejsu Management API,
  • Dostarcz raporty dla użytkownika usługi (np. w panelu administracyjnym) za pomocą interfejsu Embed API lub Core Reporting API.

Przepływ użytkowników

W tej sekcji omawiamy kwestie związane z implementacją związane z krokami procesu tworzenia konta z perspektywy użytkownika.

Użytkownik zaproponował 2 opcje włączenia Analytics w swojej usłudze:

  1. Utwórz konto Google Analytics
  2. Użyj istniejącego konta Google Analytics. Uwaga: ten proces nie jest omówiony w tym dokumencie. Więcej informacji o dostępie do danych konfiguracyjnych Google Analytics użytkownika znajdziesz w sekcji Management API.

Podczas tworzenia nowego konta Google Analytics trzeba wysłać wraz z prośbą o obsługę administracyjną informacje, takie jak nazwa konta, nazwa usługi itp. W zależności od dostępnych informacji o użytkowniku i preferowanego sposobu wyświetlania dostępne są 3 główne opcje inicjowania przepływu użytkownika po kliknięciu przez niego opcji „Utwórz konto”:

Pytaj o szczegóły konta po autoryzacji

W takim przypadku w trakcie procesu użytkownik jest proszony o podanie szczegółów konta. Proces powinien przebiegać w podobny sposób:

  1. Użytkownik jest przekierowywany do usługi konta Google na potrzeby protokołu OAuth 2.0. Jeśli użytkownik nie ma konta Google lub nie jest zalogowany, zostanie poproszony o utworzenie konta Google lub zalogowanie się.
  2. Użytkownik jest proszony o autoryzację aplikacji do tworzenia kont Google Analytics.
  3. Użytkownik akceptuje prośbę o przyznanie uprawnień aplikacji.
  4. Użytkownik jest przekierowywany do dostawcy usług. Pamiętaj, że jeśli użytkownik odmówi autoryzacji, nadal będzie przekierowywany z powrotem do dostawcy usług.
  5. Użytkownik otrzymuje formularz, który pozwala na zbieranie informacji o koncie do utworzenia (np.nazwy konta, nazwy usługi, nazwy profilu, strefy czasowej, adresu URL witryny itp.).
  6. Użytkownik wypełnia i przesyła formularz, po czym zostaje przekierowany do Google i wyświetla Warunki korzystania z usługi Google Analytics.
  7. Użytkownik akceptuje Warunki korzystania z usługi.
  8. Użytkownik zostaje przekierowany do strony dostawcy usług i widzi komunikat o powodzeniu utworzenia konta Google Analytics ze szczegółowymi informacjami o tym koncie i o tym, jak uzyskać do niego dostęp. Pamiętaj, że jeśli użytkownik nie zaakceptuje Warunków korzystania z usługi, nadal zostanie przekierowany z powrotem do dostawcy usług.

Zapytaj o szczegóły konta przed autoryzacją

W takim przypadku użytkownik jest proszony o podanie szczegółów konfiguracji konta, które ma zostać utworzone. Proces powinien przebiegać w podobny sposób:

  1. Na stronie dostawcy usług wyświetla się formularz służący do zbierania informacji o koncie do utworzenia (np. nazwy konta, nazwy usługi, nazwy profilu, strefy czasowej czy adresu URL witryny).
  2. Użytkownik wypełnia formularz, klika przycisk przesyłania i zostaje przekierowany do usługi konta Google, która obsługuje protokół OAuth 2.0. Jeśli użytkownik nie ma konta Google lub nie jest zalogowany, zostanie poproszony o utworzenie konta Google lub zalogowanie się.
  3. Użytkownik jest proszony o autoryzację aplikacji do tworzenia kont Google Analytics.
  4. Użytkownik akceptuje żądane uprawnienia aplikacji.
  5. Użytkownik jest przekierowywany do dostawcy usług.
  6. Użytkownik jest przekierowywany do Google i widzi Warunki korzystania z usługi Google Analytics.
  7. Użytkownik akceptuje Warunki korzystania z usługi.
  8. Użytkownik zostaje przekierowany do strony dostawcy usług i widzi komunikat o powodzeniu utworzenia konta Google Analytics ze szczegółowymi informacjami o tym koncie i o tym, jak uzyskać do niego dostęp.

Uzupełnij dane konta lub pomiń formularze

Jeśli informacje o koncie użytkownika są już dostępne (np. adres URL witryny, nazwa witryny, strefa czasowa itp.), można dodatkowo uprościć obie powyższe opcje:

  • Wstępne wypełnienie formularza i zezwolenie użytkownikowi na jego edycję
  • Całkowite pominięcie formularza i automatyczne utworzenie konta z wykorzystaniem istniejących informacji.