Ten dokument opisuje, jak aplikacja może uzyskać autoryzację do wysyłania żądań do interfejsu Tag Manager API.
Autoryzacja żądań
Aby użytkownik mógł wyświetlić informacje o swoim koncie w dowolnej witrynie Google, musi najpierw zalogować się na konto Google. Podobnie gdy użytkownicy po raz pierwszy uzyskują dostęp do Twojej aplikacji, muszą ją autoryzować, aby miała dostęp do swoich danych.
Każde żądanie wysyłane przez aplikację do interfejsu Tag Manager API musi zawierać token autoryzacji. Token stanowi też dla Google identyfikator aplikacji.
Informacje o protokołach autoryzacji
Twoja aplikacja musi autoryzować żądania za pomocą protokołu OAuth 2.0. Inne protokoły nie są obsługiwane. Jeśli aplikacja używa funkcji Zaloguj się przez Google, niektórymi aspektami autoryzacji nie musisz się zajmować.
Autoryzowanie żądań za pomocą protokołu OAuth 2.0
Wszystkie żądania wysyłane do interfejsu Tag Manager API muszą być autoryzowane przez użytkownika.
Szczegóły procesu autoryzacji z użyciem protokołu OAuth 2.0 różnią się nieznacznie w zależności od rodzaju projektowanej aplikacji. Do większości typów aplikacji ma zastosowanie ten ogólny proces:
- Gdy tworzysz aplikację, rejestrujesz ją, korzystając z konsoli interfejsów API Google. Następnie Google przekazuje informacje, które są potrzebne później, takie jak identyfikator klienta i tajny klucz klienta.
- Aktywuj interfejs Tag Manager API w Konsoli interfejsów API Google. (jeśli interfejsu API nie ma na liście w konsoli, pomijasz ten krok).
- Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
- Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
- Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
- Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
- Jeśli Google uzna, że żądanie i token są prawidłowe, przesyła dane, o które prosisz.
Niektóre procesy obejmują dodatkowe kroki, takie jak wykorzystanie tokenów odświeżania do uzyskania nowych tokenów dostępu. Szczegółowe informacje o procesach obowiązujących w przypadku różnych typów aplikacji znajdziesz w dokumencie Google na temat protokołu OAuth 2.0.
Informacje o zakresie OAuth 2.0 dla interfejsu Tag Manager API:
| Zakres | Znaczenie |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
Wyświetlanie kontenerów Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.edit.containers |
Zarządzanie kontenerami Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.delete.containers |
Usuń kontenery Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.edit.containerversions |
Zarządzanie wersjami kontenerów Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.publish |
Opublikuj kontenery Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.manage.users |
Zarządzanie uprawnieniami użytkowników do danych Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.manage.accounts |
Zarządzaj kontami Menedżera tagów Google. |
Aby poprosić o dostęp przy użyciu protokołu OAuth 2.0, aplikacja potrzebuje danych z zakresu oraz informacji przekazywanych przez Google po zarejestrowaniu aplikacji (takich jak identyfikator klienta i tajny klucz klienta).
Pierwsze kroki
Aby zacząć korzystać z interfejsu Tag Manager API, musisz najpierw użyć narzędzia do konfiguracji, które przeprowadzi Cię przez proces tworzenia projektu w Konsoli interfejsów API Google, włączania interfejsu API i tworzenia danych logowania.
Aby skonfigurować nowe konto usługi, wykonaj te czynności:
- Kliknij Utwórz dane logowania > Klucz konta usługi.
- Wybierz, czy chcesz pobrać klucz publiczny/prywatny konta usługi jako standardowy plik P12 czy plik JSON, który można wczytać przez bibliotekę klienta interfejsu API Google.
Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie. To jedyny egzemplarz tego klucza. Twoim obowiązkiem jest jego bezpieczne przechowywanie.
Typowe przepływy OAuth 2.0
W poniższych wytycznych przedstawiamy typowe przypadki użycia poszczególnych procesów OAuth 2.0:
Serwer WWW
Ta procedura jest przydatna w przypadku automatycznego, offline lub zaplanowanego dostępu do konta Menedżera tagów Google użytkownika.
- Automatyczne aktualizowanie informacji o Menedżerze tagów z serwera.
Po stronie klienta
Jest idealny, gdy użytkownicy wchodzą w bezpośrednie interakcje z aplikacją, aby uzyskać dostęp do konta Menedżera tagów Google w przeglądarce. Ten proces eliminuje potrzebę korzystania z funkcji po stronie serwera, ale sprawia też, że jest niepraktyczny w przypadku zautomatyzowanych, offline lub zaplanowanych raportów.
- Dostosowane narzędzie do konfiguracji w przeglądarce.
Zainstalowane aplikacje
Dotyczy aplikacji rozpowszechnianych w postaci pakietu i instalowanych przez użytkownika. Dokończenie procesu uwierzytelniania wymaga, aby aplikacja lub użytkownik miał dostęp do przeglądarki.
- Widżet na pulpicie na komputerze PC lub Mac.
- Wtyczka do systemu zarządzania treścią. Zaletą tego procesu w porównaniu z serwerem WWW lub po stronie klienta jest to, że na potrzeby aplikacji można używać jednego projektu w Konsoli interfejsów API. Ułatwia to użytkownikom instalację.
Konta usługi
Ta opcja jest przydatna w przypadku automatycznego dostępu offline/zaplanowanego dostępu do własnego konta Menedżera tagów Google. Możesz na przykład utworzyć niestandardowe narzędzie do monitorowania własnego konta Menedżera tagów Google i udostępniania go innym użytkownikom.
Rozwiązywanie problemów
Jeśli access_token utracił ważność lub w przypadku danego wywołania interfejsu API użyjesz nieprawidłowego zakresu, w odpowiedzi otrzymasz kod stanu 401.
Jeśli autoryzowany użytkownik nie ma dostępu do konta lub kontenera Menedżera tagów Google, w odpowiedzi otrzymasz kod stanu 403. Sprawdź, czy masz uprawnienia właściwego użytkownika i czy masz uprawnienia dostępu do konta lub kontenera Menedżera tagów.
OAuth 2.0 Playground
Protokół OAuth 2.0 umożliwia przejście przez cały proces autoryzacji przy użyciu interfejsu internetowego. Narzędzie wyświetla też wszystkie nagłówki żądań HTTP wymagane do utworzenia autoryzowanego zapytania. Jeśli nie możesz uzyskać autoryzacji do działania w Twojej aplikacji, spróbuj uruchomić ją za pomocą protokołu OAuth 2.0 Playground. Następnie możesz porównać nagłówki HTTP i żądanie z narzędzia testowego z tym, co wysyła aplikacja. W ten sposób będziesz mieć pewność, że żądania są prawidłowo sformatowane.
Nieprawidłowe przyznanie
Jeśli podczas próby użycia tokena odświeżania pojawi się odpowiedź o błędzie invalid_grant, może to być spowodowane przez co najmniej jedną z tych przyczyn:
- Zegar Twojego serwera nie jest zsynchronizowany z NTP.
- Przekroczono limit tokenów odświeżania.
Aplikacje mogą prosić o wiele tokenów odświeżania, aby uzyskać dostęp do jednego konta Menedżera tagów Google. Jest to przydatne np. wtedy, gdy użytkownik chce zainstalować aplikację na wielu komputerach i korzystać z tego samego konta Menedżera tagów Google. W tym przypadku wymagane są 2 tokeny odświeżania, po jednym na każdą instalację. Gdy liczba tokenów odświeżania przekroczy limit, starsze tokeny staną się nieprawidłowe. Jeśli aplikacja spróbuje użyć unieważnionego tokena odświeżania, zwracana jest odpowiedź błęduinvalid_grant. Każda unikalna kombinacja identyfikatora klienta i konta może mieć maksymalnie 25 tokenów odświeżania. (Ten limit może się zmienić). Jeśli aplikacja będzie nadal żądać tokenów odświeżania dla tej samej kombinacji identyfikatora klienta i konta, po wydaniu 26 tokena pierwszy wydany token odświeżania stanie się nieprawidłowy. 27 żądany token odświeżania unieważnia drugi wydany token itd.