Obsługa wersji

Zespół Maps JavaScript API regularnie aktualizuje interfejs API, dodając nowe funkcje, poprawki błędów i ulepszenia wydajności. Na tej stronie opisano wersje interfejsu API, których 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ślony jako v=weekly.
    Ta wersja jest aktualizowana raz w tygodniu i jest najbardziej aktualna.
  • Kanał kwartalny jest określany za pomocą v=quarterly.
    Ta wersja jest aktualizowana raz na kwartał i jest najbardziej przewidywalna.
  • Wersja beta jest określona za pomocą v=beta.
    Ta wersja jest oparta na wersji weekly i jest aktualizowana raz w tygodniu. Zawiera dodatkowe zmiany, które można przetestować i przesłać opinię.
  • Kanał alfa jest określany za pomocą v=alpha.
    Ta wersja jest oparta na wersji beta i jest aktualizowana raz w tygodniu. Obejmuje on eksperymenty, które pozwalają zbierać opinie klientów na temat prototypów. Służy on tylko do celów programistycznych i nie powinien być używany w środowisku produkcyjnym.
  • Numer wersji jest określony za pomocą v=n.nn.
    Możesz wybrać v=3.66, v=3.65, v=3.64 lub v=3.63.
    Numery wersji są aktualizowane raz na kwartał (patrz Aktualizacje kwartalne).

Jeśli nie określisz wyraźnie kanału ani wersji, domyślnie otrzymasz kanał tygodniowy. Jeśli przeniesiono Cię z abonamentu Premium i nie określono kanału ani wersji, 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 kanał tygodniowy. Jest to najnowsza i najbardziej aktualna wersja, która zawiera najnowsze poprawki błędów i ulepszenia wydajności. Możesz określić kanał tygodniowy, 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 w kanale tygodniowym jest wersja 3.66. Ta wersja jest aktualizowana co tydzień i zawiera nowe funkcje, poprawki błędów oraz ulepszenia wydajności.

W połowie listopada kanał tygodniowy zostanie zaktualizowany do wersji 3.67. W takim przypadku nowa wersja może nie zawierać wycofanych funkcji lub może nie być zgodna wstecznie.

Wybór kanału kwartalnego

W przypadku niektórych aplikacji korzystniejsze mogą być rzadsze, ale większe aktualizacje, ponieważ zapewniają większą przewidywalność. Te aplikacje powinny korzystać z kanału kwartalnego. Użyj tego podejścia, jeśli chcesz, aby poprawki błędów i ulepszenia wydajności były wprowadzane w oczekiwanym czasie (patrz aktualizacje kwartalne). Możesz określić kanał kwartalny, 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: "quarterly",
  });
  </script>

Obecnie kanał kwartalny jest w wersji 3.65. W ciągu kwartału ta wersja nie otrzymuje nowych funkcji, poprawek błędów ani ulepszeń wydajności. Co jakiś czas możemy wprowadzać w tej wersji poprawki błędów zabezpieczeń.

W połowie listopada kanał kwartalny zostanie zaktualizowany do wersji 3.66. Wtedy nowa wersja będzie zawierać nowe funkcje, usunięte zostaną wycofane funkcje lub zostaną wprowadzone zmiany, które będą oznaczać brak zgodności wstecznej z poprzednimi 3 miesiącami.

Wybór wersji beta

Użyj wersji beta, aby wypróbować nowe funkcje i zmiany w wersji beta. Funkcje w wersji beta są kompletne, ale mogą występować pewne problemy (aby je zgłosić i przesłać opinię, użyj narzędzia Issue Tracker). Wersja beta nie jest objęta gwarancją jakości usług ani nie uwzględnia jej żadna zasada wycofywania. Niektóre zmiany mogą nie być zgodne wstecznie z wcześniejszymi wersjami.

Ta wersja jest oparta na wersji weekly i jest aktualizowana raz w tygodniu.

Wersję 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>

Wybór kanału alfa

Użyj kanału alfa, aby wypróbować nowe eksperymentalne funkcje i zmiany. Aby zgłaszać problemy i przesyłać opinie, użyj narzędzia Issue Tracker. Kanał alfa nie jest objęty gwarancją jakości usług ani nie uwzględnia go żadna zasada wycofywania, a niektóre zmiany mogą nie być zgodne wstecznie z wcześniejszymi wersjami. Służy on tylko do celów programistycznych i nie powinien być używany w środowisku produkcyjnym.

Ta wersja jest oparta na wersji beta i jest aktualizowana 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

Wersję określaj 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.65,
  });
  </script>

Obecnie możesz określić v=3.66, v=3.65, v=3.64 lub v=3.63.

  • Wersja 3.66 jest aktualizowana co tydzień i zawiera nowe funkcje, poprawki błędów oraz ulepszenia wydajności.
  • Wersja 3.65 nie otrzymuje cotygodniowych aktualizacji.
  • Wersja 3.64 nie otrzymuje cotygodniowych aktualizacji.
  • Wersja 3.63 nie otrzymuje cotygodniowych aktualizacji.
  • Możemy co jakiś czas wprowadzać poprawki błędów zabezpieczeń w dowolnej wersji.
  • Podczas tworzenia nowej wersji możemy wprowadzić zmiany, które nie będą zgodne wstecznie.

Po połowie listopada będzie można określić v=3.67, v=3.66, v=3.65 lub v=3.64.

  • Wersja 3.67 będzie co tydzień otrzymywać aktualizacje z nowymi funkcjami, poprawkami błędów i ulepszeniami wydajności.
  • Wersja 3.66 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Wersja 3.65 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Wersja 3.64 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Możemy co jakiś czas wprowadzać poprawki błędów zabezpieczeń w dowolnej wersji.
  • Wersja 3.63 nie będzie już dostępna. Każda próba wczytania tej wersji zostanie zignorowana i zamiast tego otrzymasz domyślny kanał.

Na poniższym diagramie pokazano, które wersje będą dostępne w poszczególnych kanałach w ciągu najbliższego roku.

v=weekly v=quarterly v=3.nn v=3.nn-1 Sierpień 2026 r. Listopad 2026 r. Luty 2027 r. Maj 2027 r. v3.63 v3.64 v3.64 v3.65 v3.65 v3.65 v3.66 v3.66 v3.66 v3.66 v3.67 v3.67 v3.67 v3.68 v3.68 v3.69

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

Gdy zaktualizujemy kanały wersji, może to mieć wpływ na Twoją aplikację. Może się tak zdarzyć, ponieważ aplikacja korzysta z nieudokumentowanych lub wycofanych funkcji albo z powodu błędu lub wprowadzonej przez nas poprawki.

Tymczasowym rozwiązaniem jest ponowne skonfigurowanie aplikacji, aby używała starszej wersji.

  1. Otwórz konsolę w narzędziach dla programistów w przeglądarce i sprawdź wartość 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.66.2”, w tagu skryptu użyj v=3.65.
    To tymczasowe obejście będzie działać tylko przez ograniczony czas.

Po wprowadzeniu tymczasowego obejścia będziesz mieć czas (zwykle od 3 do 6 miesięcy) na zaktualizowanie aplikacji, tak aby nie korzystała już z nieudokumentowanych lub wycofanych funkcji i uwzględniała błędy lub poprawki błędów.

Następnie należy przywrócić pierwotny tag skryptu, aby wczytać interfejs API.

Możesz też utworzyć zgłoszenie do zespołu pomocy lub zgłosić problem.

Kwartalne e-maile z aktualnościami

Zespół Maps JavaScript API wydaje nową wersję raz na kwartał. Ma to miejsce w połowie lutego, maja, sierpnia i listopada. Kolejna aktualizacja nastąpi w połowie listopada. Nowy kanał tygodniowy będzie udostępniać wersję 3.67, a pozostałe kanały zostaną wtedy zaktualizowane.

Tygodniowa aktualizacja kanału

Kanał tygodniowy wskazuje obecnie wersję 3.66.

W połowie listopada wersja kanału tygodniowego zostanie zaktualizowana z 3.66 do 3.67. W tym momencie nowa wersja będzie zawierać nowe funkcje, usunięte zostaną wycofane funkcje lub zostaną wprowadzone zmiany powodujące brak zgodności wstecznej. Po zaktualizowaniu kanału może być konieczne przetestowanie tych zmian.

W ciągu 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 wprowadzi niezgodności wstecznej.

Kwartalne e-maile z aktualnościami

Kanał kwartalny wskazuje obecnie wersję 3.65.

W połowie listopada kanał kwartalny zostanie zaktualizowany z wersji 3.65 do wersji 3.66. Po aktualizacji ta wersja będzie zawierać nowe funkcje, usunięte zostaną wycofane funkcje lub zostaną wprowadzone zmiany, które nie są zgodne wstecznie, z ostatnich 3 miesięcy. Po zaktualizowaniu kanału może być konieczne przetestowanie tych zmian.

W ciągu kwartału ta wersja nie będzie zawierać nowych funkcji, poprawek błędów ani ulepszeń wydajności. Nie spowoduje to usunięcia wycofanych funkcji ani nie wprowadzi niezgodności wstecznej.

Aktualizacje wersji

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

Wersja 3.67

Nowa wersja 3.67 zostanie wydana w połowie listopada. W momencie premiery ta wersja będzie zawierać nowe funkcje, usunięte zostaną przestarzałe funkcje lub wprowadzone zostaną zmiany powodujące brak zgodności wstecznej w porównaniu z wersją 3.66. Podczas zmiany numerów wersji należy przetestować aplikację.

W tym kwartale 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 wprowadzi niezgodności wstecznej.

Wersja 3.66

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza brak zgodności wstecznej w porównaniu z wersją 3.65. Podczas zmiany numerów wersji należy przetestować aplikację.

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

Wersja 3.65

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza brak zgodności wstecznej w porównaniu z wersją 3.64. Podczas zmiany numerów wersji należy przetestować aplikację.

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 wstecznych.

Wersja 3.64

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza brak zgodności wstecznej w porównaniu z wersją 3.63. Podczas zmiany numerów wersji należy przetestować aplikację.

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 wstecznych.

Wersja 3.63

Po połowie listopada ta wersja zostanie usunięta i nie będzie można jej już używać. Każda próba wczytania tej wersji zostanie zignorowana i zamiast tego otrzymasz kanał domyślny.

Obsługa wersji

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

Sprawdzanie wersji

Do debugowania użyj właściwości google.maps.version, aby uzyskać bieżącą wersję interfejsu Maps JavaScript API w aplikacji. 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

Przewodnik dla programistów zawsze opisuje wersję cotygodniową.

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