เอกสาร / การตั้งค่า / React / Apple MapKit

การตั้งค่า Apple MapKit

ขั้นตอนการใช้ Apple MapKit JS บนเว็บผ่าน MapConductor แตกต่างจากเวอร์ชัน iOS ตรงที่ต้องใช้ JWT ที่ออกโดย Apple

PACKAGE
react-for-mapkit
API KEY
โทเคน JWT
CSS
ไม่จำเป็น
REACT
19 ขึ้นไป
ผู้ให้บริการเดียวกัน แพลตฟอร์มอื่นiOS

ก่อนเริ่ม

Node.js 18 ขึ้นไป, React 19 ขึ้นไป
บัญชีนักพัฒนา Apple และ Maps ID / คีย์ส่วนตัวของ MapKit JS
STEP 01

เตรียมโทเคน MapKit JS

สร้าง Maps ID และคีย์ส่วนตัวใน Apple Developer ลงนาม JWT ที่ฝั่งเซิร์ฟเวอร์และออกโทเคน เนื่องจากโทเคนมีวันหมดอายุ หน้าจอที่เปิดทิ้งไว้นานจึงต้องมีกลไกในการอัปเดต

ข้อควรระวัง
อย่าวางคีย์ส่วนตัวไว้ที่ฝั่ง frontend การลงนาม JWT ต้องทำที่ฝั่งเซิร์ฟเวอร์เท่านั้น
STEP 02

ติดตั้ง

MapKit JS โหลดแพ็กเกจแบบไดนามิกจาก CDN ของ Apple ไม่จำเป็นต้องเขียนแท็ก script

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

ส่งโทเคนไปยัง state hook

นอกจากการส่งโทเคนแบบคงที่แล้ว คุณยังสามารถส่ง callback ที่จัดหาและอัปเดตโทเคนได้ หากระบุทั้งสองอย่าง callback จะมีความสำคัญเหนือกว่า

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 ขึ้นไปเท่านั้น

เกิดข้อผิดพลาดเรื่องลำดับ hook เมื่อสลับ provider

  • React ไม่สามารถเปลี่ยนลำดับการเรียก hook ได้ ให้สร้างคอมโพเนนต์เล็กๆ สำหรับแต่ละ provider และเรียก hook ของ provider นั้นๆ ภายใน ไดเรกทอรี providers/ ในแอปตัวอย่างใช้โครงสร้างนี้

ถัดไป

สำหรับ provider MapKit ของ iOS ไม่จำเป็นต้องมีคีย์หรือการเริ่มต้นใช้งาน สามารถใช้โค้ดหน้าจอเดิมกันทุกแพลตฟอร์มได้