문서 / 설정 / React / HERE

HERE 설정

Web에서 HERE를 MapConductor에서 쓰는 절차입니다. HERE Maps API for JavaScript는 npm이 아니라 CDN에서 읽어 들이고, H.service.Platform을 앱 쪽에서 만들어 뷰에 넘깁니다.

PACKAGE

react-for-here

API KEY

필요

CSS

CDN에서

REACT NATIVE

있음

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

데모 보기매장 지도 · React ↗

시작하기 전에

Node.js 18 이상

HERE Platform의 API 키

STEP 01

설치한다

패키지 자체는 HERE의 JS API를 동봉하지 않습니다. 페이지 쪽에서 읽어 들인 H 글로벌을 씁니다.

terminalnpm

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

STEP 02

HERE의 JS API를 읽어 들인다

HERE 자신의 퀵스타트와 마찬가지로, CDN에서 script 태그로 읽어 들입니다. @mapconductor/react-for-here는 이것들이 공개하는 H 글로벌을 전제로 하고 있습니다.

index.htmlHTML

<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-core-legacy.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"></script>
<link rel="stylesheet" href="https://js.api.here.com/v3/3.1/mapsjs-ui.css" />

STEP 03

Platform을 만들어 뷰에 넘긴다

HERE에서는 키를 상태 훅이 아니라 H.service.Platform에 넘깁니다. Platform은 앱 쪽의 인증 정보로 만들고, 뷰의 platform props에 넘깁니다. useMemo로 만들면 다시 렌더할 때마다 다시 만들어지지 않습니다.

HereMap.tsxTypeScript · React

const platform = useMemo(
  () => new H.service.Platform({ apikey: import.meta.env.VITE_HERE_API_KEY }),
  [],
);

<HereMapView2D state={state} platform={platform}>{children}</HereMapView2D>

주의

키는 빌드 시의 환경 변수(Vite라면 import.meta.env.VITE_*)에서 넘기고, 소스 관리에는 넣지 마세요. 프런트엔드로 전달되는 이상, 공개되어도 피해가 나지 않도록 리퍼러 제한이나 도메인 제한을 반드시 겁니다.

동작 확인

여기까지 보이면 완료

HERE의 지도가 나오면 완료입니다. Web의 HERE 프로바이더는 2D 뷰뿐입니다.

HereMap.tsxTypeScript · React

import { useMemo, useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { HereMapDesign, HereMapView2D, useHereViewState } from '@mapconductor/react-for-here';

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

export function HereMap() {
  const state = useHereViewState({
    mapDesignType: HereMapDesign.NormalDay,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  // HERE Maps API for JavaScript is loaded from the CDN (see index.html);
  // the platform must be created with the host page's own credentials.
  const platform = useMemo(
    () => new H.service.Platform({ apikey: import.meta.env.VITE_HERE_API_KEY }),
    [],
  );
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <HereMapView2D state={state} platform={platform}>
      <Marker state={markerState} />
    </HereMapView2D>
  );
}

지도 디자인

HereMapDesign은 HERE의 맵 스킴에 대응합니다.

HereMapDesign

Notes

NormalDay / NormalNight

표준 스타일의 낮・밤

Satellite

위성 화상

HybridDay / HybridNight

위성 화상＋도로와 라벨

LiteDay / LiteNight

경량 스타일

LogisticsDay

물류용

잘 안 될 때

H가 undefined가 된다

index.html의 script 태그가 읽히고 있는지, 순서가 올바른지 확인합니다(core → core-legacy → service → ui → mapevents).
SSR 하고 있는 경우는, Platform의 생성을 클라이언트 쪽에서만 하도록 합니다.

지도가 나오지 않는다

H.service.Platform에 넘긴 apikey가 올바른지 확인합니다.

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

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

마커가 많은 경우는 markerTilingOptions를 넘기면, 정적인 마커 무리를 래스터 오버레이로서 한꺼번에 그립니다.