문서 / 설정 / React / Apple MapKit

Apple MapKit 설정

Web에서 Apple MapKit JS를 MapConductor에서 쓰는 절차입니다. iOS 판과 달리, Apple이 발행하는 JWT 토큰이 필요합니다.

PACKAGE

react-for-mapkit

API KEY

JWT 토큰

CSS

불필요

REACT

19 이상

같은 프로바이더, 다른 플랫폼iOS

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상, React 19 이상

Apple Developer 계정과 MapKit JS의 Maps ID / 비밀 키

STEP 01

MapKit JS의 토큰을 준비한다

Apple Developer에서 Maps ID와 비밀 키를 만들고, 서버 쪽에서 JWT를 서명해 발행합니다. 토큰에는 유효 기한이 있으므로, 오래 열어 두는 화면에서는 갱신의 구조가 필요합니다.

주의

비밀 키를 프런트엔드에 두지 마세요. JWT의 서명은 반드시 서버 쪽에서 합니다.

STEP 02

설치한다

MapKit JS는 Apple의 CDN에서 패키지가 동적으로 읽어 들입니다. script 태그를 쓸 필요는 없습니다.

terminalnpm

npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-mapkit

STEP 03

토큰을 상태 훅에 넘긴다

정적인 토큰을 넘기는 것 외에, 토큰을 공급・갱신하는 콜백을 넘길 수도 있습니다. 양쪽을 지정한 경우는 콜백이 우선됩니다.

MapKitMap.tsxTypeScript · React

const state = useMapKitViewState({
  token: import.meta.env.VITE_MAPKIT_TOKEN ?? '',
  mapDesignType: MapKitMapDesign.Standard,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});

동작 확인

여기까지 보이면 완료

MapKit의 지도가 나오면 완료입니다.

MapKitMap.tsxTypeScript · React

import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapKitMapDesign, MapKitMapView, useMapKitViewState } from '@mapconductor/react-for-mapkit';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function MapKitMap() {
  const state = useMapKitViewState({
    token: import.meta.env.VITE_MAPKIT_TOKEN ?? '',
    mapDesignType: MapKitMapDesign.Standard,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <MapKitMapView state={state} style={{ height: 480 }}>
      <Marker state={markerState} />
    </MapKitMapView>
  );
}

지도 디자인

MapKitMapDesign은 MapKit의 맵 타입에 대응합니다.

MapKitMapDesign

Notes

Standard

표준의 도로 지도

Satellite

위성 화상

Hybrid

위성 화상＋도로와 라벨

MutedStandard

데이터를 얹는 바탕용

SatelliteFlyover / HybridFlyover

Flyover 대응 지역용

잘 안 될 때

지도가 나오지 않는다

토큰이 빈 문자열이 되어 있지 않은지 확인합니다.
토큰의 유효 기한이 지나지 않았는지 확인합니다. 오래 여는 화면에서는 authorizationCallback으로 갱신해 주세요.

React 18에서 빌드할 수 없다

이 패키지만 React 19 이상을 요구합니다.

프로바이더를 전환하면 훅의 순서 오류가 나온다

React는 훅의 호출 순서를 바꿀 수 없습니다. 프로바이더마다 작은 컴포넌트를 만들고, 그 안에서 그 프로바이더의 훅을 호출하는 형태로 합니다. 샘플 앱의 providers/ 디렉터리가 이 구성입니다.

iOS 판의 MapKit 프로바이더는 키도 초기화도 불필요합니다. 같은 화면 코드인 채로, 플랫폼마다 나눠 쓸 수 있습니다.