W tym dokumencie znajdziesz informacje o tym, jak aplikacja może uzyskać autoryzację do wysyłania żądań do interfejsu Tag Manager API.
Autoryzowanie żądań
Zanim użytkownicy będą mogli wyświetlić informacje o swoim koncie w dowolnej witrynie Google, muszą najpierw zalogować się na konto Google. Podobnie gdy użytkownicy po raz pierwszy uzyskują dostęp do Twojej aplikacji, muszą autoryzować ją, aby mogła uzyskać dostęp do ich 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 uwierzytelnionego 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.
Oto zakres danych protokołu OAuth 2.0 dla interfejsu Tag Manager API:
| Zakres | Znaczenie |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
Wyświetl kontener Menedżera tagów Google. |
https://www.googleapis.com/auth/tagmanager.edit.containers |
Zarządzaj 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ądzać 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 rozpocząć korzystanie 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 i włączania interfejsu API.
Aby skonfigurować nowe konto usługi:
- Kliknij Utwórz dane logowania > Klucz konta usługi.
- Wybierz, czy chcesz pobrać klucz publiczny lub prywatny konta usługi jako standardowy plik P12, czy jako plik JSON, który można wczytać za pomocą biblioteki 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
Poniższe wytyczne przedstawiają typowe przypadki użycia poszczególnych przepływów OAuth 2.0:
Serwer internetowy
Ten proces jest odpowiedni w przypadku automatycznego, offline’owego 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
Idealne rozwiązanie, gdy użytkownicy wchodzą w interakcję z aplikacją, aby uzyskać dostęp do konta Menedżera tagów Google w przeglądarce. Ten proces eliminuje konieczność korzystania z funkcji po stronie serwera, ale utrudnia automatyczne, offline’owe i zaplanowane raportowanie.
- spersonalizowane narzędzie do konfiguracji oparte na przeglądarce;
Zainstalowane aplikacje
W przypadku aplikacji rozpowszechnianych w postaci pakietu i instalowanych przez użytkownika. Wymaga to dostępu aplikacji lub użytkownika do przeglądarki, aby ukończyć proces uwierzytelniania.
- Widżet na komputerze PC lub Macu.
- Wtyczka do systemu zarządzania treścią. Zaletą tego procesu w porównaniu z procesem po stronie serwera lub klienta jest to, że w przypadku aplikacji można użyć jednego projektu w konsoli interfejsu API. Ułatwia to użytkownikom instalację.
Konta usługi
Przydatne w przypadku zautomatyzowanego, offline’owego lub 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ępnić je innym użytkownikom.
Rozwiązywanie problemów
Jeśli Twój access_token wygasł lub używasz nieprawidłowego zakresu w przypadku danego wywołania interfejsu API, 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. Upewnij się, że masz autoryzację odpowiedniego użytkownika i że przyznano Ci uprawnienia do uzyskiwania dostępu do konta lub kontenera Menedżera tagów.
OAuth 2.0 Playground
OAuth 2.0 Playground umożliwia przejście przez cały proces autoryzacji w interfejsie internetowym. Narzędzie wyświetla też wszystkie nagłówki żądań HTTP wymagane do wysłania autoryzowanego zapytania. Jeśli nie możesz uzyskać autoryzacji w swojej aplikacji, spróbuj uzyskać ją w narzędziu OAuth 2.0 Playground. Następnie możesz porównać nagłówki i żądania HTTP z playgroundu z tym, co wysyła Twoja aplikacja. To prosty sposób na sprawdzenie, czy żądania są prawidłowo sformatowane.
Nieprawidłowe uprawnienia
Jeśli podczas próby użycia tokena odświeżania otrzymasz odpowiedź z błędem invalid_grant, może to być spowodowane jednym z tych powodów:
- Zegar 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. w sytuacjach, gdy użytkownik chce zainstalować aplikację na wielu komputerach i uzyskać dostęp do tego samego konta Menedżera tagów Google. W takim przypadku wymagane są 2 tokeny odświeżania – po jednym dla każdej instalacji. Gdy liczba tokenów odświeżania przekroczy limit, starsze tokeny staną się nieważne. Jeśli aplikacja spróbuje użyć unieważnionego tokena odświeżania, zwrócona zostanieinvalid_grantodpowiedź z błędem. Każda unikalna kombinacja identyfikatora klienta i konta może mieć maksymalnie 25 tokenów odświeżania. (Pamiętaj, że ten limit może ulec zmianie). Jeśli aplikacja nadal będzie żą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ę nieważny. 27 prośba o odświeżenie tokena unieważnia 2 wydany token i tak dalej.