ТОП 5 ошибок API Maps и их исправления

Ошибки Google Maps API могут нарушить работу самых важных функций вашего приложения — превратив отслеживание местоположения, поиск адресов и навигацию в реальном времени в разочаровывающие тупики. Это руководство разбирает пять самых распространённых ошибок Google Maps API и предоставляет пошаговые решения для восстановления работы ваших карт.

Один из способов упростить интеграцию карт — использовать Adalo — конструктор приложений без кода для веб-приложений на основе баз данных и нативных приложений iOS и Android — одна версия на всех трёх платформах, опубликованная в Apple App Store и Google Play. Встроенные компоненты карт Adalo автоматически обрабатывают конфигурацию ключа API на всех платформах, устраняя распространённые ошибки, такие как несовпадающие параметры между сборками iOS и Android.

Независимо от того, отлаживаете ли вы ошибку MissingKeyMapError или устраняете неполадки с разрешениями геолокации, эти решения помогут вам быстрее запустить функции на основе местоположения и охватить пользователей в веб-приложениях и мобильных магазинах приложений.

Добавление карты в приложение может привести к разочаровывающим ошибкам, если конфигурация установлена неправильно. От отсутствующих ключей API до ограниченного доступа — эти проблемы часто приводят к пустым картам, водяным знакам или неработающим функциям. Вот краткий разбор пяти наиболее распространённых Геолокация и картирование ошибок и их решений:

• MissingKeyMapError: вызывается отсутствием или неправильной конфигурацией ключей API. Исправьте её, создав правильный ключ API, включив необходимые API и добавив ключ в приложение.
• RefererNotAllowedMapError: происходит, когда URL приложения или идентификатор не авторизованы. Отрегулируйте ограничения реферера HTTP в Google Cloud Console, чтобы решить эту проблему.
• ApiNotActivatedMapError: происходит, когда необходимые API не включены. Активируйте все необходимые API и привяжите учётную запись выставления счётов.
• InvalidApiKeyMapError: указывает на неправильный или неузнанный ключ API. Дважды проверьте ключ, параметры проекта и учётную запись выставления счётов.
• GeolocationPermissionDenied/NoResults: результат отказа в разрешении на доступ к местоположению или отсутствия данных о местоположении. Убедитесь, что обработаны разрешения во время выполнения и включены API, такие как Geolocation.

Эти ошибки могут нарушить ключевые функции приложения, такие как отслеживание местоположения и геокодирование. Быстрое исправление обеспечивает безупречный пользовательский опыт. Хотите узнать все подробности? Читайте дальше, чтобы получить пошаговые решения.

Почему ошибки карт важны для разработчиков приложений

Функциональность карт занимает центральное место в бесчисленных мобильных приложениях — от отслеживания доставки и совместного использования поездок до просмотра недвижимости и фитнес-приложений. Когда возникают ошибки Google Maps API, они не просто отображают сообщение об ошибке; они нарушают основные пользовательские взаимодействия, на которые полагаются ваши клиенты.

Для разработчиков приложений, использующих такие платформы, как Adalo — конструктор приложений без кода для веб-приложений на основе баз данных и нативных приложений iOS и Android — одна версия на всех трёх платформах, опубликованная в Apple App Store и Google Play — понимание этих ошибок имеет решающее значение. Хотя Adalo обрабатывает большую часть сложности интеграции карт через встроенные компоненты, знание способов устранения неполадок на уровне API гарантирует безупречную работу функций на основе местоположения на всех платформах.

Хорошая новость: большинство ошибок Google Maps API возникают из-за проблем с конфигурацией, а не из-за проблем с кодом. Как только вы поймёте коренные причины, решения обычно будут простыми.

1. MissingKeyMapError

Причина ошибки

Бесплатная версия является одной из самых щедрых: MissingKeyMapError происходит, когда ключ API либо отсутствует, либо неправильно настроен в приложении. Это может означать, что ключ отсутствует в AndroidManifest.xml файле или не установлен с помощью GMSServices на iOS. С 22 июня 2016 года Google требует, чтобы каждый запрос к Google Maps API включал действительный ключ API, связанный с проектом с включённым выставлением счётов — даже для пользователей уровня free. Без этого Google не может аутентифицировать ваш запрос, и карта не загрузится.

Симптомы или влияние на приложения iOS/Android

Когда возникает эта ошибка, карта приложения может отображаться как пустой серый прямоугольник или показывать водяной знак, указывающий на то, что она находится в режиме разработки. Функции, такие как выбор местоположения, геокодирование и отслеживание в реальном времени, не будут работать. Кроме того, в консоли будет выведена следующая ошибка:

«Ошибка Google Maps JavaScript API: MissingKeyMapError».

Это может привести к тому, что приложение покажется пользователям неработающим, потенциально вызывая разочарование и негативные отзывы.

Пошаговое решение

• Создание и конфигурация ключа API:
  Перейдите в Google Cloud Console и откройте страницу «Учётные данные». Создайте новый ключ API и убедитесь, что ваш проект имеет включённое выставление счётов.
• Включение необходимых API:
  Активируйте API, специфичные для вашей платформы:
  • Geocoding API (для веб-приложений или гибридных приложений)
  • Maps SDK для Android
  • Maps SDK для iOS
• Правильная реализация ключа:
  • Для веб-приложений или WebView: Добавьте ключ в качестве параметра в тег скрипта:

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"></script>

  • Для Android: Включите ключ API в AndroidManifest.xml файл в <meta-data> тег внутри <application> элемент.
  • Для iOS: Установите ключ в AppDelegate файл, используя:

    GMSServices.provideAPIKey("YOUR_API_KEY")

• Проверка конфигурации:
  Используйте расширение Chrome Google Maps Platform API Checker или откройте вкладку «Сеть» в браузере, чтобы подтвердить, что ключ отправляется с запросами API. Если проблема сохраняется, временно отключите ограничения ключей (такие как IP-адреса или Bundle ID), чтобы определить, заключается ли проблема в ограничениях или в самом ключе.

Далее мы рассмотрим RefererNotAllowedMapError и способ её решения.

2. RefererNotAllowedMapError

Причина ошибки

Бесплатная версия является одной из самых щедрых: RefererNotAllowedMapError возникает, когда URL или идентификатор, используемый для загрузки Maps JavaScript API, не включен в список авторизованных источников для вашего ключа API в Google Cloud Console. Это частая проблема в гибридных мобильных приложениях, созданных с помощью фреймворков, таких как Ionic или Cordova, так как эти приложения часто работают по протоколу file:// file://.

Это также может произойти, если ключ API настроен с неправильным типом ограничения, например с использованием ограничения по IP-адресу вместо ограничения по HTTP-источникам. Кроме того, в приложениях iOS или Android, использующих WebView, механизм рендеринга может удалить заголовок Referer Referer

Симптомы или влияние на приложения iOS/Android

в целях конфиденциальности, что вызывает сбои при применении ограничений веб-сайта. Когда эта ошибка возникает, карта может загрузиться с затемненным или инвертированным внешним видом и отобразить водяной знак «только для целей разработки» Google Maps API error: RefererNotAllowedMapError . Хотя технически карта загружена, она становится непригодной для использования. Сообщение об ошибке

обычно появляется в консоли JavaScript, но в мобильных приложениях оно не отображается непосредственно на устройстве. Chrome DevTools (Android) или Вместо этого вам нужно использовать инструменты удаленной отладки, такие как Safari Web Inspector

Пошаговое решение

• (iOS) для просмотра ошибки в консоли. Ниже приведено четкое руководство по решению этой проблемы. , такие как Войдите в Google Cloud Console и перейдите к
• APIs & Services (APIs и сервисы) > Credentials (Учетные данные) для редактирования вашего ключа API..
• В разделе «Application restrictions» (Ограничения приложения) выберите file:// HTTP referrers (web sites) (HTTP-источники (веб-сайты))
  • Если ваше приложение использует протокол __file_url__//android_asset/*
  • file://: __file_url__//var/containers/*
• Заменить file:/ с __file_url__ Для Android добавьте: file:// file:///*
• Для iOS добавьте: *.yourdomain.com/* file:///*
• Убедитесь, что Geocoding API, Places API, и Distance Matrix API в ограничения ключа для
• источников.
• Для стандартных веб-мобильных сайтов используйте подстановочные знаки, такие как

https://*.example.com/*	для включения всех поддоменов и путей.	Убедитесь, что Maps JavaScript API
включены в разделе «API restrictions» (Ограничения API).	Сохраните изменения и подождите не менее 5 минут, чтобы они распространились глобально.	*.example.com/*
Очистите кэш приложения или браузера, чтобы избежать загрузки кэшированных ошибок.	Сохраните изменения и подождите не менее 5 минут, чтобы они распространились глобально.	__file_url__//var/containers/* (iOS) или __file_url__//android_asset/* Платформа/Среда
Нативный iOS	Приложения iOS	Тип ограничения com.company.appname)
Нативный Android	Приложения Android	Рекомендуемый формат

Стандартный веб-сайт

Причина ошибки

Бесплатная версия является одной из самых щедрых: ApiNotActivatedMapError HTTP-источники

https://example.com/*

Симптомы или влияние на приложения iOS/Android

iOS/Android (гибридное)

Пошаговое решение

• file://*(Android) Bundle ID (например, com.example.app) или Package Name + SHA-1 Fingerprint , такие как 3. ApiNotActivatedMapError
• появляется, когда ваш ключ API действителен, но конкретный сервис Google Maps, который вы пытаетесь использовать, не был активирован в проекте Google Cloud Console. Поскольку Google работает по модели оплаты по факту использования, вам необходимо включить требуемые API и подключить биллинг-аккаунт для продолжения.Частой ошибкой является включение Maps JavaScript API, но забывание активировать Maps SDK для Android или iOS. Даже если вы находитесь в пределах бесплатного лимита использования, эта ошибка может возникнуть, если ваш биллинг-аккаунт отсутствует или неактивен. Когда эта ошибка возникает, карта в вашем приложении может отображаться как пустая или затемненная область с водяным знаком «только для целей разработки». Функции, такие как поиск адреса, расчет расстояния или функции «рядом со мной», перестанут работать. Вы также заметите ошибку, записанную в консоль JavaScript браузера или в журналы удаленной отладки для приложений iOS и Android., найдите следующие API и нажмите Ограничьте первоначальную загрузку до для каждого:
  • Geocoding API
  • Maps SDK для Android
  • Maps SDK для iOS
  • Places API
  • Distance Matrix API
• Настройка платежей: Перейдите в Выставление счетов раздел и свяжите свой платежный счет, используя действительную кредитную карту.
• Проверьте ограничения ключа API: В разделе Учетные данныевыберите свой ключ API и убедитесь, что его ограничения разрешают доступ к вновь включенным SDK.
• Ожидание и перезагрузка: Подождите около 5 минут, пока изменения вступят в силу, затем перезагрузите приложение или очистите кэш.

Требования API/SDK по платформам

Платформа	Требуемый API/SDK
Веб-приложения	Geocoding API
Приложения Android	Maps SDK для Android
Приложения iOS	Maps SDK для iOS
Все платформы (функции)	Geocoding API, Places API, Geolocation API

4. InvalidApiKeyMapError

Причина ошибки

Бесплатная версия является одной из самых щедрых: InvalidApiKeyMapError возникает, когда серверы Google не распознают ключ API, используемый в вашем приложении. В отличие от проблем, связанных с ограничениями, эта ошибка указывает на то, что сам ключ либо неправильный, либо не распознан системой. Распространенные причины включают опечатки при копировании ключа, использование ключа из удаленного проекта Google Cloud или попытку использовать недавно созданный ключ до его полной репликации (этот процесс обычно занимает 5–10 минут).

Симптомы или влияние на приложения iOS/Android

Когда эта ошибка появляется, вы заметите затемненную карту или отрицательное изображение Street View с водяным знаком "только для разработки". На веб-платформах консоль JavaScript четко отобразит Google Maps JavaScript API error: InvalidKeyMapError. Для разработчиков Android Logcat покажет ошибку java.io.IOException: Server returned: 3, а разработчики iOS смогут найти InvalidKeyMapError сообщение в веб-инспекторе.

Эта ошибка не только затемняет карту, но и отключает функции, такие как поиск адресов и булавки местоположения.

Пошаговое решение

• Еще раз проверьте ключ API, получив его из Google Cloud Console > Учетные данные и сравнив его посимвольно с тем, что находится в коде вашего приложения. Даже небольшая опечатка может вызвать эту ошибку.
• Убедитесь, что ваш проект Google Cloud активен и не был удален.
• Перейти на Когда эта ошибка возникает, карта в вашем приложении может отображаться как пустая или затемненная область с водяным знаком «только для целей разработки». Функции, такие как поиск адреса, расчет расстояния или функции «рядом со мной», перестанут работать. Вы также заметите ошибку, записанную в консоль JavaScript браузера или в журналы удаленной отладки для приложений iOS и Android. и подтвердите, что "Maps SDK для Android" и "Maps SDK для iOS" включены.
• Проверьте, что в вашем проекте есть действительный платежный счет. Способ оплаты требуется даже если вы находитесь в пределах бесплатного уровня.
• Если вы только что создали новый ключ, подождите 5–10 минут для его репликации перед повторным тестированием.

В таблице ниже указаны требуемые конфигурации для каждой платформы:

Платформа	Требуемая конфигурация	Где проверить
Android	Имя пакета и отпечаток SHA-1	AndroidManifest.xml и ограничения ключей в Cloud Console
iOS	Идентификатор комплекта (Bundle ID)	Параметры проекта Xcode и ограничения ключей в Cloud Console
Веб/JS	HTTP-реферер (URL)	Адресная строка браузера и ограничения ключей в Cloud Console

Как исправить ошибку Google Maps API "RefererNotAllowedMapError" – Краткое руководство по восстановлению доступа к карте

5. GeolocationPermissionDenied или NoResults

Ошибки геолокации могут нарушить работу карты, даже если проблемы с ключом API отсутствуют.

Что вызывает ошибку?

GeolocationPermissionDenied возникает, когда ваше приложение не может получить доступ к данным о местоположении устройства. Это может быть потому, что пользователи явно отказывают в доступе к местоположению при появлении запроса, или приложение не запрашивает необходимые разрешения. На Android отсутствие ACCESS_COARSE_LOCATION или ACCESS_FINE_LOCATION в вашем AndroidManifest.xml приведет к этой ошибке. Кроме того, если службы определения местоположения отключены в параметрах устройства, ни одно приложение не сможет получить данные GPS.

NoResults (HTTP 404 notFound) возникает, когда API геолокации получает допустимый запрос, но не может определить местоположение. Это может произойти, если соседние точки доступа WiFi или вышки сотовой сети не распознаны для триангуляции. Другие потенциальные причины включают отключение API геолокации в Google Cloud Console или отсутствие действительного платежного счета.

Как это влияет на приложения iOS и Android

Когда GeolocationPermissionDenied возникает, пользователи могут столкнуться с сообщением "Местоположение недоступно". На Android синяя точка "Мое местоположение" может не отображаться, и нажатие кнопки "Мое местоположение" не переместит карту на позицию пользователя. Функции, такие как отслеживание в реальном времени, геоограждение и определение режима передвижения, также перестанут работать.

За NoResults ошибок, ваше приложение получит HTTP 404 ответ с кодом причины notFound. Вы также можете заметить необычно большой радиус точности в ответе, что указывает на то, что сервис переходит на геолокацию на основе IP, поскольку не может идентифицировать конкретные точки доступа WiFi или вышки сотовой связи. В документации Google Geolocation API объясняется:

Запрос был корректным, но результаты не возвращены.

Как исправить эти ошибки

Вот как решить каждую проблему пошагово:

Исправление GeolocationPermissionDenied:

• Убедитесь, что ваше приложение запрашивает разрешения на доступ к местоположению во время выполнения, прежде чем пытаться получить доступ к данным о местоположении.
• Для Android (уровень API 23+) убедитесь, что вы правильно обрабатываете запросы разрешений во время выполнения. Если пользователи отклоняют разрешения, отключите функции, основанные на местоположении, и уведомите их.
• Убедитесь, что ACCESS_COARSE_LOCATION и ACCESS_FINE_LOCATION включены в ваш AndroidManifest.xml. Для iOS подтвердите, что необходимые конфигурации установлены в вашем списке свойств.
• Проверьте, что Службы определения местоположения включены в параметрах системы устройства.

Исправление NoResults:

• Включите Geolocation API, Geocoding API, Places API и соответствующие Maps SDKs для Android и iOS в Google Cloud Console.
• Подтвердите, что ваш проект имеет действительный связанный платежный счет, так как Google требует кредитную карту даже для использования бесплатного уровня.
• Для устранения ошибок 404 установите considerIp параметр на false в вашем запросе. Если вы все еще получаете ответ 404, это означает, что предоставленное wifiAccessPoints и cellTowers не может быть геолокализовано.
• Дважды проверьте ограничения вашего ключа API, чтобы убедиться, что они соответствуют конфигурации вашего приложения.

Упрощение интеграции карт с современными конструкторами приложений

Хотя понимание этих ошибок API необходимо для устранения неполадок, современные платформы разработки приложений могут значительно снизить сложность интеграции карт. Adalo, конструктор приложений на базе искусственного интеллекта, предлагает встроенные компоненты карт, которые автоматически обрабатывают большую часть конфигурации.

С помощью подхода Adalo вы настраиваете ключ Google Maps API один раз в централизованном месте, и платформа правильно применяет его для веб-сборок, iOS и Android. Это устраняет распространенные ошибки, такие как несовпадающие конфигурации платформ или забытые включения API. Функция платформы Волшебное добавление позволяет добавить функциональность на основе местоположения, описав то, что вам нужно — «добавить карту, показывающую ближайшие рестораны» — и она генерирует соответствующие компоненты с правильными конфигурациями.

Для приложений, которые должны масштабироваться, модульная инфраструктура Adalo поддерживает приложения с более 1 миллиона ежемесячных активных пользователей. В отличие от веб-оболочек, которые могут испытывать проблемы с производительностью отрисовки карт при большой нагрузке, Adalo компилирует в истинный собственный код iOS и Android, обеспечивая плавное взаимодействие с картами даже в требовательных сценариях. Платные планы включают неограниченные записи базы данных, поэтому данные о местоположении для тысяч достопримечательностей не превысят лимиты хранилища.

Платформа также обрабатывает сложность публикации как в Apple App Store, так и в Google Play Store из единой кодовой базы — включая надлежащие конфигурации ключей API для каждой платформы, которые часто озадачивают разработчиков.

Заключение

Ошибки API карт на iOS и Android часто сводятся к простым проблемам конфигурации. Наиболее распространенные причины включают отсутствующие или недействительные ключи API, проблемы с платежным счетом, ограничения реферера, отключенные API, и ошибки разрешения местоположения. Решение этих проблем на ранней стадии помогает избежать печально известного водяного знака «только для целей разработки», обеспечивает, что функции не выйдут из строя во время скачков трафика, и обеспечивает бесперебойную работу функциональности на основе местоположения для пользователей.

Чтобы все шло гладко, регулярно проверяйте Google Cloud Console, чтобы убедиться, что все необходимые API включены. Используйте отдельные ключи API для iOS и Android для эффективного управления квотами использования и применяйте ограничения приложений — такие как названия пакетов, идентификаторы пакета или HTTP-рефереры — для защиты ваших ключей от неправомерного использования.

Запрашивайте у пользователей разрешения на доступ к местоположению в нужный момент, например после входа, чтобы предотвратить ошибки «Местоположение недоступно». Для проблем, связанных с квотами, реализуйте экспоненциальную задержку, чтобы распределить запросы и дать серверу время на восстановление. Эти небольшие корректировки могут сильно повлиять на надежность и бесперебойность функций карт на различных платформах.

Для тех, кто создает приложения на основе местоположения без традиционного кодирования, Adalo упрощает весь процесс с помощью централизованного управления ключами API и встроенной обработкой разрешений местоположения — позволяя вам сосредоточиться на функциях, а не на трудностях конфигурации.

Похожие посты в блоге

• Google Maps SDK для Android: руководство для начинающих
• Как встраивать интерактивные карты в приложения без кода
• Распространённые ошибки API в приложениях без кода
• Контрольный список интеграции MapKit для приложений iOS

Часто задаваемые вопросы

Почему выбрать Adalo вместо других решений для создания приложений?

Adalo — это приложение для создания приложений на базе ИИ, которое создает истинные нативные приложения для iOS и Android. В отличие от веб-оболочек, оно компилируется в нативный код и публикуется напрямую в Apple App Store и Google Play Store из единой кодовой базы — самая сложная часть запуска приложения выполняется автоматически.

Какой самый быстрый способ создать и опубликовать приложение в App Store?

Интерфейс Adalo с перетаскиванием в сочетании со сборкой с помощью искусственного интеллекта через Magic Start и Magic Add позволяет создавать полные приложения за часы вместо недель. Платформа обрабатывает весь процесс отправки в App Store, поэтому вам не нужно вручную разбираться в сложных требованиях Apple.

Какие шаги я могу предпринять, чтобы избежать ошибок API карт в моем приложении?

Начните с проверки настройки вашего ключа API — убедитесь, что ключ активен, правильно настроен и ограничен подходящими доменами или приложениями. Включите выставление счетов на вашем счете, так как большинство API карт не будут работать без него. Установите надежную обработку ошибок со стратегиями повтора, такими как экспоненциальная задержка, для работы с ограничениями скорости или проблемами квот.

Почему мой ключ API не работает даже после устранения неполадок?

Проверьте четыре ключевые области: Конфигурация (ключ правильно настроен и отформатирован?), Ограничения (совпадают ли параметры IP, домена или приложения с вашим приложением?), Доступ к API (включены ли необходимые API в Google Cloud?) и Статус выставления счетов (активно ли выставление счетов и связано ли?). Если вы все еще застряли, попробуйте полностью переосмыслить ключ API.

Почему Google Maps API требует выставление счетов даже для использования бесплатного уровня?

Google требует данные для выставления счетов для эффективного управления учетными записями и пресечения неправомерного использования. Хотя пользователи получают ежемесячный кредит для компенсации затрат, информация о выставлении счетов отслеживает использование кредита и применяет его правильно. Эта установка помогает Google контролировать деятельность, предотвращать злоупотребления и помогать разработчикам оставаться в пределах лимитов использования.

Сколько времени требуется для создания приложения на основе карт?

При традиционной разработке одна только интеграция карт может занять дни конфигурации. Используя встроенные компоненты карт Adalo и сборку с помощью искусственного интеллекта, вы можете иметь функциональное приложение на основе местоположения за несколько часов. Платформа автоматически обрабатывает конфигурацию ключей API на всех платформах.

Мне нужно ли иметь опыт кодирования, чтобы добавить карты в мое приложение?

Нет, если вы используете современные конструкторы приложений. Визуальный интерфейс Adalo позволяет добавлять компоненты карт путем перетаскивания, а затем настраивать их через простые панели параметров. Для более сложных функций местоположения Magic Add позволяет вам описать то, что вы хотите, на обычном языке.

Могу ли я опубликовать приложение на основе карт как для iOS, так и для Android?

Да. Adalo создает собственные приложения для обеих платформ из единой сборки. Вы настраиваете ключ Google Maps API один раз, и платформа применяет правильные параметры в соответствии с требованиями каждой платформы — устраняя распространенную ошибку несовпадающих конфигураций между iOS и Android.

Как правильно обрабатывать разрешения на доступ к местоположению в моем приложении?

Запрашивайте разрешения в подходящие моменты — например, когда пользователь впервые попытается использовать функцию определения местоположения, а не сразу при запуске приложения. Объясните, почему вам нужен доступ к местоположению, прежде чем появится системный запрос. Всегда предусмотрите альтернативную функциональность для пользователей, которые откажут в разрешении.

Что вызывает водяной знак «только в целях разработки» на картах?

Этот водяной знак появляется, когда ваш ключ API неправильно настроен, выставление счетов не включено, требуемые API не активированы или ограничения реферера не совпадают с доменом вашего приложения. Следуйте инструкциям по устранению неполадок для MissingKeyMapError, RefererNotAllowedMapError или ApiNotActivatedMapError в зависимости от вашей конкретной ситуации.