Obsługa wersji

Zespół Maps JavaScript API regularnie aktualizuje interfejs API, dodając do niego nowe funkcje, poprawki błędów i ulepszenia wydajności. Na tej stronie opisaliśmy wersje interfejsu API, które możesz używać w swoich aplikacjach.

Kanały wersji i numery wersji

W aplikacji możesz określić kanały wersji lub numery wersji:

  • Kanał cotygodniowy jest określany za pomocą v=weekly.
    Ten kanał jest aktualizowany raz w tygodniu i zawiera najnowsze informacje.
  • Kanał kwartalny jest określony za pomocą parametru v=quarterly.
    Ten kanał jest aktualizowany raz na kwartał i jest najbardziej przewidywalny.
  • Kanał beta jest określony za pomocą v=beta.
    Ten kanał powstał na podstawie kanału weekly i jest aktualizowany raz w tygodniu. Zawiera też dodatkowe zmiany dotyczące wstępnych testów i opinii.
  • Kanał alfa jest określony za pomocą parametru v=alpha.
    Ten kanał powstał na podstawie kanału beta i jest aktualizowany raz w tygodniu. Obejmuje eksperymenty z opiniami klientów na temat prototypów. Służy ona tylko do celów programistycznych i nie powinna być używana w wersji produkcyjnej.
  • Numer wersji jest określony za pomocą v=n.nn.
    Masz do wyboru v=3.58, v=3.57, v=3.56 lub v=3.55.
    Numery wersji są aktualizowane raz na kwartał (patrz Aktualizacje kwartalne).

Jeśli nie określisz kanału ani wersji, domyślnie otrzymasz kanał tygodniowy. Jeśli Twoja migracja z abonamentu premium nie została jednoznacznie wskazana przez kanał ani wersję, domyślnie otrzymasz kanał kwartalny. Jeśli podasz nieprawidłową wersję, otrzymasz kanał domyślny.

Wybór kanału tygodniowego

W przypadku większości aplikacji zalecamy korzystanie z kanału tygodniowego. To najnowsza wersja, która zawiera najnowsze poprawki błędów i ulepszenia wydajności. Kanał tygodniowy możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
    (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
      key: "YOUR_API_KEY",
      v: "weekly",
    });
  </script>

Obecnie kanał tygodniowy ma wersję 3.58. Ta wersja jest aktualizowana co tydzień o nowe funkcje, poprawki błędów i ulepszenia działania.

W połowie listopada zaktualizujemy wersję cotygodniowego kanału do wersji 3.59. W tym czasie nowa wersja może usunąć wycofane funkcje lub wprowadzić niezgodności wsteczne.

Wybieranie kanału kwartalnego

Niektóre aplikacje mogą korzystać z mniejszej liczby większych aktualizacji, ponieważ zapewnia to większą przewidywalność. W przypadku tych aplikacji należy korzystać z kanału kwartalnego. Stosuj to podejście, jeśli chcesz, aby poprawki błędów i ulepszenia wydajności były dostępne w oczekiwanym terminie (patrz comiesięczne aktualizacje). Możesz określić kanał kwartalny, wczytając Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "quarterly",
  });
  </script>

Obecnie kanał kwartalny ma wersję 3.57. W ciągu kwartału ta wersja nie otrzymuje nowych funkcji, poprawek błędów ani ulepszeń działania. Co jakiś czas możemy wprowadzać w tej wersji poprawki błędów związanych z zabezpieczeniami.

W połowie listopada kwartalny kanał zostanie zaktualizowany do wersji 3.58. Wtedy nowa wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niezgodności wstecz od poprzednich 3 miesięcy.

Wybieranie wersji beta

Korzystaj z kanału wersji beta, aby wypróbować nowe funkcje i zmiany w wersji beta. Funkcje w wersji beta są już w pełni gotowe, ale mogą występować problemy z nierozwiązanymi problemami (aby zgłosić problemy i przesłać opinię, skorzystaj z narzędzia do śledzenia problemów). Kanały beta nie są objęte gwarancją jakości usług ani żadnymi zasadami wycofywania, a niektóre zmiany mogą nie być zgodne ze starszymi wersjami.

Ten kanał bazuje na kanale weekly i jest aktualizowany raz w tygodniu.

Kanał beta możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "beta",
  });
  </script>

Wybieranie kanału alfa

Korzystając z kanału alfa, możesz wypróbować nowe eksperymentalne funkcje i zmiany. Aby zgłaszać problemy i przesyłać opinie, użyj śledzika problemów. Kanału alfa nie obejmuje żadna gwarancja jakości usług ani żadna zasada wycofywania, a niektóre zmiany mogą nie być zgodne wstecznie z wcześniejszymi wersjami. Służy ona tylko do celów programistycznych i nie powinna być używana w wersji produkcyjnej.

Ten kanał powstał na podstawie kanału beta i jest aktualizowany raz w tygodniu.

Kanał alfa możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "alpha",
  });
  </script>

Wybieranie numeru wersji

Określ wersję za pomocą numeru tylko wtedy, gdy regularnie testujesz i aktualizujesz aplikację. Dzieje się tak, ponieważ wersje numerowane są ostatecznie usuwane, gdy co kwartał tworzone są nowe wersje. Numer wersji możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: 3.57,
  });
  </script>

Obecnie możesz określić v=3.58, v=3.57, v=3.56 lub v=3.55.

  • Wersja 3.58 jest aktualizowana co tydzień o nowe funkcje, poprawki błędów i ulepszenia wydajności.
  • Wersja 3.57 nie otrzymuje cotygodniowych aktualizacji.
  • Wersja 3.56 nie otrzymuje cotygodniowych aktualizacji.
  • Wersja 3.55 nie otrzymuje cotygodniowych aktualizacji.
  • Możemy co jakiś czas wprowadzać poprawki błędów związanych z bezpieczeństwem do dowolnej wersji.
  • Podczas tworzenia nowej wersji możemy wprowadzić zmiany niezgodne wstecznie.

Po połowie listopada będzie można wybrać: v=3.59, v=3.58, v=3.57 lub v=3.56.

  • Wersja 3.59 będzie co tydzień otrzymywać aktualizacje z nowymi funkcjami, poprawkami błędów i ulepszeniami wydajności.
  • Wersja 3.58 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Wersja 3.57 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Wersja 3.56 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Możemy co jakiś czas wprowadzać poprawki błędów związanych z bezpieczeństwem do dowolnej wersji.
  • Wersja 3.55 nie będzie już dostępna. Każda próba wczytania tej wersji zostanie zignorowana i zamiast niej otrzymasz kanał domyślny.

Na diagramie poniżej widać, które wersje będą dostępne w poszczególnych kanałach w przyszłym roku.

v=weekly v=quarterly v=3.nn v=3.nn-1 Aug 2024 Nov 2024 Feb 2025 May 2025 v3.55 v3.56 v3.56 v3.57 v3.57 v3.57 v3.58 v3.58 v3.58 v3.58 v3.59 v3.59 v3.59 v3.60 v3.60 v3.61

Aktualizacja wpłynęła na moją aplikację

Gdy zaktualizujemy kanały wersji, może to wpłynąć na Twoją aplikację. Może to być spowodowane tym, że aplikacja korzysta z nieudokumentowanych lub wycofanych funkcji albo z powodu błędu lub wprowadzonej przez nas poprawki.

Aby tymczasowo obejść problem, możesz ponownie skonfigurować aplikację do używania starszej wersji.

  1. Otwórz konsolę w narzędziach dla programistów w przeglądarce i sprawdź wartość zmiennej google.maps.version.
  2. Zaktualizuj tag skryptu, który wczytuje interfejs API, i poproś o starszy numer wersji.
    Jeśli na przykład google.maps.version to „3.58.2”, w tagu skryptu użyj wartości v=3.57.
    To tymczasowe obejście będzie działać tylko przez ograniczony czas.

Gdy wdrożysz tymczasowe obejście, będziesz mieć czas (zazwyczaj 3–6 miesięcy), aby zaktualizować aplikację, aby nie używała już funkcji bez dokumentacji lub wycofanych funkcji, oraz uwzględnić błędy i ich poprawki.

Następnie przywróć pierwotny tag skryptu, aby wczytać interfejs API.

Możesz też przesłać zgłoszenie lub zgłosić problem.

Kwartalne e-maile z aktualnościami

Raz na kwartał zespół Maps JavaScript API udostępnia nową wersję. Dotyczy to połowy lutego, maja, sierpnia i listopada. Następna aktualizacja nastąpi w połowie listopada. Nowy kanał tygodniowy będzie zawierać wersję 3.59. Wtedy też zostaną zaktualizowane inne kanały.

Cotygodniowe informacje o kanale

Kanał tygodniowy odnosi się obecnie do wersji 3.58.

W połowie listopada kanał tygodniowy zostanie zaktualizowany z wersji 3.58 na wersję 3.59. Nowa wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niekompatybilność wsteczną. Po zaktualizowaniu kanału może być konieczne przetestowanie tych zmian.

W ciągu tego kwartału nowa wersja będzie co tydzień aktualizowana o nowe funkcje, poprawki błędów i ulepszenia wydajności. Nie spowoduje to usunięcia wycofanych funkcji ani nie spowoduje niezgodności wstecznej.

Kwartalny raport o kanale

Kanał kwartalny wskazuje obecnie wersję 3.57.

W połowie listopada zaktualizujemy kanał kwartalny z wersji 3.57 do wersji 3.58. Po aktualizacji ta wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niezgodności wsteczne z ostatnich 3 miesięcy. Po zaktualizowaniu kanału może być konieczne przetestowanie tych zmian.

W tym kwartale ta wersja nie będzie zawierać nowych funkcji, poprawek błędów ani ulepszeń działania. Nie spowoduje to usunięcia wycofanych funkcji ani nie spowoduje niezgodności wstecznej.

Aktualizacje wersji

W połowie listopada numery wersji są przenoszone, aby uwzględnić wydanie nowej wersji.

Wersja 3.59

Nowa wersja 3.59 zostanie udostępniona w połowie listopada. Po wydaniu ta wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niezgodności wstecz w stosunku do wersji 3.58. Aplikację należy przetestować po zmianie numeru wersji.

W trakcie kwartału nowa wersja będzie co tydzień aktualizowana o nowe funkcje, poprawki błędów i ulepszenia wydajności. Nie spowoduje to usunięcia wycofanych funkcji ani nie spowoduje niezgodności wstecznej.

Wersja 3.58

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza niezgodności wsteczne w stosunku do wersji 3.57. Aplikację należy przetestować po zmianie numeru wersji.

Po połowie listopada ta wersja nie będzie już aktualizowana o nowe funkcje, poprawki błędów ani ulepszenia działania. Nie spowoduje usunięcia wycofanych funkcji ani nie wprowadzi niezgodności wstecznej.

Wersja 3.57

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza niezgodności wsteczne w porównaniu z wersją 3.56. Aplikację należy przetestować po zmianie numeru wersji.

Ta wersja nie będzie już aktualizowana o nowe funkcje, poprawki błędów ani ulepszenia wydajności. Nie usunie funkcji wycofanych po tej wersji i nie wprowadzi nowych niezgodności wstecznej.

Wersja 3.56

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza niezgodności wsteczne w porównaniu z wersją 3.55. Aplikację należy przetestować po zmianie numeru wersji.

Ta wersja nie będzie już aktualizowana o nowe funkcje, poprawki błędów ani ulepszenia wydajności. Nie usunie funkcji wycofanych po tej wersji i nie wprowadzi nowych niezgodności wstecznej.

Wersja 3.55

Po połowie listopada ta wersja zostanie usunięta i nie będzie można jej już używać. Każda próba załadowania tej wersji zostanie zignorowana, a zamiast niej wyświetli się kanał domyślny.

Obsługa wersji

W każdym kwartale dostępne są 4 wersje. Obsługiwane są wszystkie te 4 wersje.

Sprawdzanie wersji

Na potrzeby debugowania użyj właściwości google.maps.version, aby uzyskać w aplikacji bieżącą wersję interfejsu Maps JavaScript API. Poniższy przykładowy kod zapisuje wersję interfejsu API w konsoli przeglądarki. (więcej informacji o konsoli przeglądarki znajdziesz w  przewodniku po sprawdzaniu błędów w przeglądarce).

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    defer></script>
  </body>
</html>

Dokumentacja wersji interfejsu API

W przewodniku dla deweloperów zawsze opisano wersję cotygodniową.

Oprócz tego dla każdej wersji jest osobna referencja: