Все знают, что вы можете использовать Google Maps, чтобы добавить карту на свой сайт, но знаете ли вы, что у Apple тоже есть JS SDK?
Эта история изначально была опубликована на phiilu.com.
Бьюсь об заклад, в какой-то момент вашей карьеры разработчика вас попросили или вы хотели реализовать интерактивную карту на своем веб-сайте. Интерактивные карты отлично подходят для визуализации местоположений и маршрутов для пользователей и заменили необходимость использования карт старой школы, помогая нам ориентироваться в реальном мире!
Итак, теперь вы находитесь на пути к реализации такой функции, и первое, что вы сделаете, это выполните поиск в Google «Как реализовать интерактивную карту на веб-сайте», и, вероятно, первые несколько результатов укажут вам использовать Google Maps. Но что, если я скажу вам, что Google - не единственный игрок в этой игре, и что есть еще и другие поставщики карт!
В этом посте мы сосредоточимся на Apple Maps! Да, вы правильно расслышали Apple Maps. Но разве Apple Maps не отстой? Apple Maps на веб-сайте? Я думал, что это существует только на iOS? вы можете спросить, и ответы будут, как обычно, это зависит от обстоятельств и да, это существует! .
Вы знаете, что Apple выпустила Apple Mapkit for JS в 2015 году, и с этого года вы можете внедрять Apple Maps на веб-сайтах! Самый популярный сервис, который я могу найти с помощью Apple Maps, - это DuckDuckGo. Если вы выполните поиск где находится вена, вы найдете небольшую карту справа от результатов поиска с помощью Apple Maps. Если вы нажмете на нее, вы будете перенаправлены на сайт с большей картой.
Хорошо, теперь вы знаете, что можете использовать Apple Maps на своем веб-сайте, но как заставить их работать? Что ж, это не так просто, как кажется, потому что Apple обрабатывает ключ API иначе, чем Google Maps.
Обычно, когда вы хотите использовать услугу, вы регистрируетесь на их сайте и генерируете ключ API, который затем можете использовать. Вместо этого Apple предоставит вам закрытый ключ, который вы можете использовать для создания токенов JSON Web Token (JWT), которые будут использоваться для проверки вашего доступа к Apple Maps. Вот почему нам нужен внутренний код, чтобы скрыть этот закрытый ключ, и поэтому мы реализуем это с помощью бессерверной функции.
В этом посте я покажу вам, как получить учетные данные от Apple, создать небольшой пример с использованием бессерверной функции Apple Maps + и, наконец, развернуть его с помощью Netlify.
Предпосылки
- Вам потребуется платное членство Apple Developer, иначе вы не сможете загрузить учетные данные для использования Apple Maps.
- Бесплатная учетная запись Netlify, чтобы иметь возможность развернуть окончательный веб-сайт
К сожалению, вам нужно быть участником программы Apple Developer, если вы хотите следовать за ней, и если вы не можете следовать ей, вы все равно можете проверить окончательную версию здесь и взглянуть на код на GitHub.
Получение учетных данных от Apple
Я не придумал эти шаги самостоятельно, и их тоже можно найти на веб-сайте Apple.
Сначала перейдите на страницу учетной записи вашего членства в Apple Developer. Нам нужно создать две вещи: идентификатор карты и закрытый ключ MapKit JS.
Идентификатор карты
На боковой панели выберите Сертификаты, идентификаторы и профили, а затем Идентификаторы и нажмите маленький значок плюса.
Затем дайте ему описание и идентификатор, используя обратный домен maps.com.phiilu.example, и нажмите Продолжить и Зарегистрироваться.
Теперь вы создали идентификатор карты, который нам понадобится для нашего закрытого ключа.
Закрытый ключ MapKit JS
Вернувшись на страницу обзора Сертификаты, идентификаторы и профили, выберите Ключи и создайте новый ключ, щелкнув маленький значок плюса.
Дайте ключу имя, и вы должны увидеть MapKit JS в качестве опции в сервисах. Если нет, значит, вы не создавали Maps ID.
Затем выберите «Настроить» рядом с MapKit JS, выберите ранее созданный идентификатор карты и нажмите Сохранить. Проверьте свои настройки и нажмите Продолжить.
Вы увидите сводку служб, которые вы включили для этого ключа, и сможете зарегистрировать свой ключ с помощью Регистрации.
Наконец, ваш ключ зарегистрирован, и вы можете его скачать! Как указано в предупреждении, это ОДНОРАЗОВАЯ ЗАГРУЗКА, и вы не сможете повторно загрузить ключ.
Вы загрузите файл с именем AuthKey_Z11AA36DZ4.p8 или аналогичный, и если вы откроете его, вы найдете 6 строк текста, которые будут вашим закрытым ключом.
Этот ключ должен ВСЕГДА оставаться закрытым и никогда не передаваться в открытый доступ, поэтому нам нужно создать бессерверную функцию для безопасного хранения ключа в бэкэнд-коде.
Также обратите внимание на сгенерированный идентификатор ключа, потому что он вам понадобится позже.
ID команды
ID команды уже создан для вас, но вам нужно скопировать его справа вверху рядом с вашим именем.
Теперь, когда у нас есть все необходимое, и мы можем начать интеграцию Apple Maps на наш веб-сайт.
Настройка среды разработки
В этом проекте используется Netlify CLI, поэтому вам нужно будет установить его глобально с помощью npm.
npm install netlify-cli -gЗатем вам нужно будет клонировать репозиторий git и проверить ветку tutorial-start.
git clone [email protected]:phiilu/apple-maps-example.git cd apple-maps-example && git checkout tutorial-start
Для запуска проекта вам необходимо установить зависимости и запустить сервер разработки.
npm install npm start
Когда вы откроете браузер по адресу http://localhost:18080, вы увидите простой веб-сайт, на который мы будем добавлять Apple Maps.
Для простоты мы будем использовать базовый HTML, стандартный Javascript и стили с использованием Tailwind. Он будет скомпилирован с использованием Parcel, а бессерверные функции можно будет протестировать локально с помощью Netlify CLI.
Объяснение структуры проекта
Внутри каталога проекта выполните следующую команду, чтобы вывести список всех папок и файлов.
tree -I 'dist|node_modules' . ├── README.md ├── netlify.toml ├── package-lock.json ├── package.json ├── postcss.config.js ├── src │ ├── functions │ ├── index.html │ ├── index.js │ └── index.pcss └── tailwind.config.js 2 directories, 9 files
Большинство этих файлов не нуждаются в объяснении, но я объясню самые интересные из них.
netlify.toml
netlify.toml содержит конфигурацию для Netlify и Netlify CLI.
Он сообщит Netlify, где находятся наши бессерверные функции, какую версию Node.js мы хотим использовать, какой порт должен запускать сервер разработки, как он может запустить наш проект в режиме разработки, и перенаправит все запросы от /api/* на правильный Netlify функция.
каталог src
src будет содержать весь код, который мы пишем. Он содержит каталог functions, в который мы будем помещать наши бессерверные функции и наши файлы HTML, Javascript и CSS.
Попутный ветер
Первоначальный CSS-фреймворк для быстрого создания нестандартных дизайнов. - tailwindcss.com
Многие другие файлы, которые вы видите, предназначены для настройки Tailwind. Мне просто нравится использовать Tailwind, чтобы добавлять стили в свои проекты, но мы не будем добавлять больше стилей, поэтому вам не нужно знать, как это работает.
Добавление Apple Maps на сайт
Давайте начнем добавлять Apple Maps на сайт! Когда вы откроете клонированное репо и откроете файл index.html, вы увидите, что Apple MapKit уже загружен из Apple.
Эта строка загрузит последнюю версию MapKit от Apple. Узнать, как Apple версии MapKit, можно здесь.
Внизу файла вы найдете div, куда мы хотим установить Apple Maps.
Этот div установил height и несколько классов, которые сделают его немного лучше. Если вы откроете http://localhost:18080/, вы увидите простой веб-сайт с навигацией, полем поиска и пустым пространством с тенью вокруг.
Теперь мы хотим добавить Apple Maps к этому div, поэтому откройте файл index.js и вставьте этот код:
Теперь вы должны увидеть карту в вашем браузере… ну, не совсем так. Если вы посмотрите на консоль, вы увидите ошибку и предупреждение.
Давайте отладим наш код и выясним, почему он не работает.
Как видите, мы правильно монтируем карту, используя id из apple-maps, который мы указали в файле index.html.
Но перед установкой мы вызываем mapkit.init(...) и получаем новый токен от /api/token. С помощью этого токена Apple Maps проверяет, что этот сайт имеет доступ к Apple Maps, но мы еще не писали код, который генерировал бы такой токен.
В следующем разделе мы напишем бессерверную функцию, которая будет генерировать наш токен для Apple Maps.
Создание бессерверной функции для создания действительного токена JWT для Apple Maps
Пришло время взять наш сгенерированный закрытый ключ и использовать его для генерации токенов JWT для нашего интерфейса!
Настройте .env с нашими секретами
Перед тем, как работать над бессерверной функцией, нам нужно будет создать .env файл в корне вашего проекта и ввести полученные нами учетные данные.
Введите информацию, которую вы сохранили из предыдущих разделов.
APPLE_MAPS_KEY немного особенный, потому что мы загрузили его как файл. Вам нужно будет скопировать содержимое файла и заменить все разрывы строк на \n. Ваша APPLE_MAPS_KEY запись должна выглядеть так:
Не волнуйтесь, это не мой настоящий закрытый ключ
Ваш .env файл должен выглядеть примерно так:
Написание бессерверной функции
Создайте папку token внутри папки functions и откройте ее в своем редакторе. Затем создайте каркас package.json, используя npm внутри папки token.
npm init -y
Как я уже упоминал, нам нужно сгенерировать токены JWT, поэтому мы будем использовать jsonwebtoken пакет.
npm i jsonwebtoken
Теперь создайте файл с именем token.js и вставьте этот код:
Эта простая функция сгенерирует токен JWT, подписанный с использованием вашего закрытого ключа. Закрытый ключ должен заменить \\n реальным \n, потому что Netlify каким-то образом добавляет это автоматически. Я нашел решение через этот комментарий на GitHub.
Токен будет действителен для 1 day и будет работать только на веб-сайте, настроенном в SITE_ORIGIN. Вы можете изменить эти параметры, если хотите, и настроить их в соответствии со своими потребностями.
Apple задокументировала, что такое каждое поле и для чего используется, в своей документации.
Перезагрузите сервер разработки и откройте http://localhost:18080/, и вы должны увидеть карту с центром в Вене 🥳
Разверните веб-сайт в Netlify
Теперь, когда наша карта работает, мы хотим опубликовать наш небольшой проект на Netlify, и мы сделаем это с помощью интерфейса командной строки Netlify, который вы уже знаете.
Если вы не вошли в Netlify с помощью интерфейса командной строки, вам сначала придется это сделать.
netlify login
Затем перейдите в корень каталога вашего проекта и запустите netlify deploy. Это поможет вам создать сайт на Netlify.
netlify deploy This folder isn't linked to a site yet ? What would you like to do? + Create & configure a new site ? Team: Florian Kapfenberger's team Choose a unique site name (e.g. isnt-phiilu-awesome.netlify.app) or leave it blank for a random name. You can update the site name later. ? Site name (optional): apple-maps-example Site Created Admin URL: https://app.netlify.com/sites/apple-maps-example URL: https://apple-maps-example.netlify.app Site ID: 44aa1f3e-f887-47e0-bf55-4c80f2ec01ab Deploy path: /Users/florian/Code/privat/projects/apple-maps-example/dist Functions path: /Users/florian/Code/privat/projects/apple-maps-example/src/functions Configuration path: /Users/florian/Code/privat/projects/apple-maps-example/netlify.toml Deploying to draft URL... ✔ Finished hashing 10 files and 1 functions ✔ CDN requesting 9 files and 1 functions › Warning: › {} › TypeError: Cannot read property '0' of undefined
Как видите, в первый раз у меня возникла ошибка, поэтому я перезапустил сценарий, и он сработал!
netlify deploy Deploy path: /Users/florian/Code/privat/projects/apple-maps-example/dist Functions path: /Users/florian/Code/privat/projects/apple-maps-example/src/functions Configuration path: /Users/florian/Code/privat/projects/apple-maps-example/netlify.toml Deploying to draft URL... ✔ Finished hashing 10 files and 1 functions ✔ CDN requesting 9 files and 1 functions ✔ Finished uploading 10 assets ✔ Deploy is live! Logs: https://app.netlify.com/sites/apple-maps-example/deploys/5f7b795ed6d83e3ab0a3f4a2 Website Draft URL: https://5f7b795ed6d83e3ab0a3f4a2--apple-maps-example.netlify.app
Наш сайт может быть развернут, но он все еще не работает, потому что нам нужно сначала настроить переменные среды в Netlify.
Откройте netlify.com, войдите в систему, перейдите к настройкам Сборка и развертывание созданного проекта и добавьте переменные среды из вашего .env файла.
Последний шаг - снова развернуть ваш проект, но на этот раз с флагом --prod.
netlify deploy --prod
Ваш проект запущен, и вы можете посетить его по URL-адресу, который вам отображает Netlify CLI, или вы можете проверить мой на https://apple-maps-example.netlify.app/
Добавление окна поиска с помощью Apple Maps (необязательно)
На данный момент мы просто отображали карту, но не взаимодействовали с ней. В этом разделе я хочу показать вам, как можно легко искать города и переходить к ним, используя всего несколько строк кода.
Откройте index.js и добавьте к нему следующие строки:
Используя new mapkit.Search(...), мы можем создать экземпляр Search и использовать его для поиска местоположений на карте.
Строки document.getElementById(...) будут использоваться для получения ссылок на элементы form и input страницы.
Получив ссылку, мы можем добавить прослушиватель событий для события submit в form. Мы предотвращаем даже настройку по умолчанию, которая перезагружает страницу и получает текст из searchBoxElement.
Далее выполняем поиск с использованием search.search(...). Первый аргумент - это запрос, а второй будет обратным вызовом, когда запрос будет завершен. Если у нас нет ошибки, мы будем использовать map.setRegionAnimated(data.boundingRegion) для перехода к найденному месту на карте.
Попробуйте! Откройте http://localhost:18080/ или https://apple-maps-example.netlify.app/ и найдите такой город, как Берлин, и нажмите Enter. Вы увидите карту перехода к центру Берлина.
Если это сработает, вы можете применить свои изменения с помощью netlify deploy --prod.
