Uygulamaya Harita Ekleme: MapLibre ile Web, React Native ve Flutter Rehberi

Üç Parçayı Tanıyın

MapLibre GL, açık kaynak bir harita motorudur; Google Maps SDK'nın yaptığı işi, kilitli bir ekosisteme bağlanmadan yapar. Motorun ihtiyacı olan her şeyi biz barındırıyoruz:

1. 01

   Stil JSON: haritanın görünümü

   Hangi katman hangi renkte, hangi yazı tipi nerede. 13 hazır temamız var; galeriden seçin ya da kurumsal kimliğinize özel tasarlatın.

2. 02

   TileJSON: veri sözleşmesi

   Tile'ların adresini, zoom aralığını ve katman şemasını bildiren küçük bir JSON. Erişim kapımız burada çalışır; harita gösterimleri de burada sayılır.

3. 03

   Vektör tile: haritanın kendisi

   OpenStreetMap verisinden ürettiğimiz, Cloudflare'ın küresel ağından sunulan parçalar. Bir harita açılışı ortalama 30 tile ister; hepsi ücrete değil tek gösterime sayılır.

Web Sitesine Harita Ekleme (Düz HTML)

En kısa yol. Alan adınız lisanslıysa başka hiçbir kimlik gerekmez; sunucumuz isteği yapan alan adını lisans listesiyle karşılaştırır.

<link href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.js"></script>

<div id="harita" style="height: 420px"></div>

<script>
  const map = new maplibregl.Map({
    container: "harita",
    style: "https://tiles.hititmedya.com/v1/styles/hitit-light.json",
    center: [32.85, 39.93],
    zoom: 5.2,
  });
  map.addControl(new maplibregl.NavigationControl());
</script>

hitit-light yerine galerideki herhangi bir stil kimliğini yazabilirsiniz: hitit-dark, hitit-grayscale, hitit-piri-reis...

Alan adınız henüz lisanslı değilse harita yüklenmez ve konsolda 403 access_denied görürsünüz; yanıtın gövdesi sizi doğrudan erişim sayfamıza yönlendirir. Kod ayarınız doğruysa lisans tanımlandığı anda aynı sayfa çalışmaya başlar.

React ve Next.js

Paketi kurun: npm install maplibre-gl. Harita bir DOM kütüphanesi olduğu için bileşen istemcide çalışmalı; Next.js App Router kullanıyorsanız dosyanın başına "use client" koymanız yeterli.

"use client";

import { useEffect, useRef } from "react";
import maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

export function Harita() {
  const kutu = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!kutu.current) return;
    const map = new maplibregl.Map({
      container: kutu.current,
      style: "https://tiles.hititmedya.com/v1/styles/hitit-light.json",
      center: [32.85, 39.93],
      zoom: 5.2,
    });
    return () => map.remove();
  }, []);

  return <div ref={kutu} style={{ height: 420 }} />;
}

Temizlik fonksiyonundaki map.remove() önemli: React 19 StrictMode geliştirmede effect'i iki kez çalıştırır, remove edilmeyen harita WebGL context sızdırır.

Performans ipucu: haritayı sayfanın ilk yükünde değil, görünüme yaklaştığında başlatın. Kendi sitemizde MapLibre paketini IntersectionObserver ile tembel yüklüyoruz; motor yalnızca kullanıcı haritaya kaydırınca iniyor.

Native Uygulamada Kimlik: Lisans Anahtarı

Buraya kadar her şey alan adıyla çalıştı. Native uygulamada ise tarayıcı yok, dolayısıyla istekle birlikte gönderilen bir alan adı da yok. Bu yüzden iOS ve Android'de kimlik, URL ile taşınan bir lisans anahtarıdır:

hm_live_4jzqi3295c02xmrxxi22hl7h   canli anahtar
hm_test_...                        gelistirme anahtari

Kurulumun tek farklı adımı şu: stil JSON'unu alın, içindeki veri kaynağının adresine anahtarınızı ekleyin. Sunucumuz anahtarlı TileJSON yanıtındaki tile adreslerine anahtarı kendisi taşır; yani bu tek satır bütün istek zincirini kimliklendirir.

const yanit = await fetch("https://tiles.hititmedya.com/v1/styles/hitit-light.json");
const stil = await yanit.json();
stil.sources.hitit.url += "?key=hm_live_SIZIN_ANAHTARINIZ";

React Native

Topluluğun resmi paketi @maplibre/maplibre-react-native. Stili yukarıdaki gibi hazırlayıp doğrudan bileşene verin:

import { useEffect, useState } from "react";
import { MapView, Camera } from "@maplibre/maplibre-react-native";

const STIL_URL = "https://tiles.hititmedya.com/v1/styles/hitit-light.json";
const ANAHTAR = "hm_live_SIZIN_ANAHTARINIZ";

export function Harita() {
  const [stil, setStil] = useState(null);

  useEffect(() => {
    fetch(STIL_URL)
      .then((y) => y.json())
      .then((s) => {
        s.sources.hitit.url += `?key=${ANAHTAR}`;
        setStil(JSON.stringify(s));
      });
  }, []);

  if (!stil) return null;

  return (
    <MapView style={{ flex: 1 }} mapStyle={stil}>
      <Camera centerCoordinate={[32.85, 39.93]} zoomLevel={5.2} />
    </MapView>
  );
}

Paket API'leri sürümler arasında değişebiliyor; prop adları farklıysa kaynaklardaki resmi dokümana bakın. Değişmeyen şey kimlik modeli: kaynak adresine ?key= eklemek.

Flutter

Paket: maplibre_gl. Aynı desen, Dart ile:

import 'package:http/http.dart' as http;
import 'package:maplibre_gl/maplibre_gl.dart';

const stilUrl = 'https://tiles.hititmedya.com/v1/styles/hitit-light.json';
const anahtar = 'hm_live_SIZIN_ANAHTARINIZ';

Future<String> stilHazirla() async {
  final yanit = await http.get(Uri.parse(stilUrl));
  return yanit.body.replaceFirst(
    'https://tiles.hititmedya.com/planet.json',
    'https://tiles.hititmedya.com/planet.json?key=$anahtar',
  );
}

// build icinde:
MapLibreMap(
  styleString: stil, // stilHazirla() sonucu
  initialCameraPosition: const CameraPosition(
    target: LatLng(39.93, 32.85),
    zoom: 5.2,
  ),
)

Anahtar Güvenliği Üzerine Dürüst Bir Not

İstemci tarafında çalışan her harita servisinde anahtar, uygulama paketinin içinde bulunabilir durumdadır; bu Google Maps SDK için de böyledir, bizim için de. Güvenlik modeli anahtarın gizli kalmasına değil, yönetilebilir olmasına dayanır:

• Her anahtar bir etikete bağlıdır ve kullanımı gösterge panelimizde ayrı izlenir.
• Sızdığından şüphelendiğiniz anahtarı bize bildirirsiniz; saniyeler içinde askıya alır, yenisini tanımlarız. Uygulamanızın yeni sürümü yeni anahtarla çıkar.
• Tarayıcıda çalışan projelerde anahtar KULLANMAYIN; alan adı kimliği hem daha güvenli hem daha hızlıdır. Anahtar yalnızca native içindir.

Fiyat ve Erişim

Hitit Medya Maps lisanslı bir hizmettir; paketler aylık 100 bin gösterimlik Starter'dan başlar, üst paketlerde özel harita tasarımı da dahildir. Güncel rakamlar ve talep formu erişim sayfasında. Neden ücretsiz bir katman sunmadığımızı ve Google Maps ile nasıl konumlandığımızı merak ediyorsanız bu yazıda uzun uzun anlattık.

Sık Sorulan Sorular

Kaynaklar