Places UI Kit ile Etkileşimli Mağaza Bulma Aracı oluşturma

Hedef

Bu belgede, Google Haritalar Platformu'nu (özellikle Maps JavaScript API ve Places UI Kit: Yer Ayrıntıları Öğesi) kullanarak etkileşimli bir mağaza bulma uygulaması geliştirmenin temel adımları açıklanmaktadır. Mağaza konumlarını gösteren bir harita oluşturmayı, görünür mağazaların listesini dinamik olarak güncellemeyi ve her mağaza için zengin yer bilgileri göstermeyi öğreneceksiniz.

Ön koşullar

Aşağıdaki konulara aşina olmanız önerilir:

  • Maps JavaScript API: Sayfanızda harita göstermek ve Places UI Kit'i içe aktarmak için kullanılır.
  • Gelişmiş İşaretçiler - Haritada işaretçileri göstermek için kullanılır.
  • Places UI Kit: Kullanıcı arayüzünde mağazalarınızla ilgili bilgileri göstermek için kullanılır.

Projenizde Maps JavaScript API ve Places UI Kit'i etkinleştirin.

Başlamadan önce Maps JavaScript API'yi yüklediğinizi ve Gelişmiş İşaretçiler ile Places UI Kit için gerekli kitaplıkları içe aktardığınızı doğrulayın. Bu belgede, HTML, CSS ve JavaScript dahil olmak üzere web geliştirme hakkında bilgi sahibi olduğunuz varsayılır.

İlk kurulum

İlk adım, sayfaya harita eklemektir. Bu harita, mağaza konumlarınızla ilgili pinleri göstermek için kullanılır.

Sayfaya harita eklemenin iki yolu vardır:

  1. gmp-map HTML web bileşenini kullanma
  2. JavaScript kullanma

Kullanım alanınıza en uygun yöntemi seçin. Haritanın her iki şekilde de uygulanması bu kılavuzla çalışır.

Demo

Bu demoda, mağaza bulucunun nasıl çalıştığına dair bir örnek gösterilmektedir. Örnekte, San Francisco Körfez Bölgesi'ndeki Google ofislerinin konumları gösterilmektedir. Her konum için yer ayrıntıları öğesi ve bazı örnek özellikler gösterilir.

Mağaza konumlarını yükleme ve görüntüleme

Bu bölümde, mağaza verileriniz haritaya yüklenip gösterilir. Bu kılavuzda, mevcut mağazalarınızla ilgili bilgileri çekebileceğiniz bir bilgi deposuna sahip olduğunuz varsayılır. Mağaza verileriniz, veritabanınız gibi çeşitli kaynaklardan gelebilir. Bu örnekte, her biri bir mağaza konumunu temsil eden bir mağaza nesneleri dizisi içeren yerel bir JSON dosyası (stores.json) olduğunu varsayıyoruz. Her nesne en az bir name, location (lat ve lng ile) ve place_id içermelidir.

Mağaza konumlarınızın yer kimliklerini henüz edinmediyseniz bu kimlikleri almanın çeşitli yolları vardır. Daha fazla bilgi için Yer Kimliği dokümanlarını inceleyin.

stores.json dosyanızdaki örnek bir mağaza ayrıntıları girişi aşağıdaki gibi görünebilir. Ad, Konum (enlem/boylam) ve Yer Kimliği alanları vardır. Mağazanın çalışma saatlerini tutan bir nesne var (kısaltılmıştır). Mağaza konumunun özel özelliklerini tanımlamaya yardımcı olan iki boole değeri de vardır.

{
  "name": "Example Store Alpha",
  "location": { "lat": 51.51, "lng": -0.12 },
  "place_id": "YOUR_STORE_PLACE_ID",
  "opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
  "new_store_design": true,
  "indoor_seating": false
}

JavaScript kodunuzda mağaza konumlarınızın verilerini getirin ve her biri için haritada bir işaretçi gösterin.

Bunu nasıl yapabileceğinize dair bir örneği aşağıda bulabilirsiniz. Bu işlev, mağazaların ayrıntılarını içeren bir nesne alır ve her birinin konumuna göre bir işaretçi oluşturur.

function displayInitialMarkers(storeLocations) {
    if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
    storeLocations.forEach(store => {
        if (store.location) {
            const marker = new AdvancedMarkerElement({
                position: new LatLng(store.location.lat, store.location.lng),
                title: store.name
            });
            mapElement.appendChild(marker);
        }
    });
}

Mağazalarınızı yükledikten ve konumlarını gösteren raptiyeler haritada gösterildikten sonra, HTML ve CSS kullanarak her bir mağazanızla ilgili ayrıntıları göstermek için bir kenar çubuğu oluşturun.

Bu aşamada mağaza bulucunuzun nasıl görünebileceğine dair bir örnek:

resim

Harita Görüntü Alanı Değişikliklerini Dinleme

Performansı ve kullanıcı deneyimini optimize etmek için uygulamanızı, işaretçileri ve ayrıntıları yalnızca ilgili konumlar görünür harita alanında (görünüm alanı) olduğunda kenar çubuğunda gösterecek şekilde güncelleyin. Bu işlemde, harita görüntü alanı değişiklikleri dinlenir, bu etkinlikler sekmeye alınır ve ardından yalnızca gerekli işaretçiler yeniden çizilir.

Haritanın boşta kalma etkinliğine bir etkinlik işleyici ekleyin. Bu etkinlik, herhangi bir kaydırma veya yakınlaştırma işlemi tamamlandıktan sonra tetiklenerek hesaplamalarınız için sabit bir görüntü alanı sağlar.

map.addListener('idle', debounce(updateMarkersInView, 300));

Yukarıdaki kod snippet'i idle etkinliğini dinler ve debounce işlevini çağırır. Debounce işlevi kullanmak, işaretçi güncelleme mantığınızın yalnızca kullanıcı haritayla kısa bir süre etkileşim kurmayı bıraktıktan sonra çalışmasını sağlayarak performansı artırır.

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

Yukarıdaki kod, bir örnek sekmeyi kaldırma işlevidir. Boşta kalma işleyicisine iletildiği görülebilen bir işlev ve gecikme bağımsız değişkeni alır. 300 ms'lik bir gecikme, kullanıcı arayüzüne fark edilebilir bir gecikme eklemeden haritanın hareket etmeyi bırakmasını beklemek için yeterlidir. Bu zaman aşımı süresi dolduktan sonra, iletilen işlev (bu örnekte updateMarkersInView) çağrılır.

updateMarkersInView işlevi aşağıdaki işlemleri yapmalıdır:

Haritadaki mevcut tüm işaretçileri temizleme

Mağazanın konumunun mevcut harita sınırları içinde olup olmadığını kontrol edin. Örneğin:

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

Yukarıdaki if ifadesinde, mağaza konumu harita görüntü alanına giriyorsa işaretçileri görüntülemek ve yan çubuktaki mağaza ayrıntılarını saklamak için kod yazın.

Yer Ayrıntıları Öğesi'ni kullanarak zengin yer ayrıntıları gösterme

Bu aşamada uygulamada tüm mağaza konumları gösterilir ve kullanıcılar bunları harita görünüm alanına göre filtreleyebilir. Bunu geliştirmek için Yer Ayrıntıları Öğesi kullanılarak her mağaza hakkında fotoğraflar, yorumlar ve erişilebilirlik bilgileri gibi zengin ayrıntılar eklenir. Bu örnekte özellikle Place Details Compact Element kullanılmaktadır.

Veri kaynağınızdaki her mağaza konumunun karşılık gelen bir Place ID'si olmalıdır. Bu kimlik, Google Haritalar'daki konumu benzersiz bir şekilde tanımlar ve ayrıntılarını getirmek için gereklidir. Bu yer kimliklerini genellikle önceden edinir ve her bir mağaza kaydınızla birlikte saklarsınız.

Uygulamaya Place Details Compact Element'i entegre edin

Bir mağazanın mevcut harita görüntü alanında olduğu ve kenar çubuğunda oluşturulduğu belirlendiğinde, bu mağaza için dinamik olarak bir yer ayrıntıları kompakt öğesi oluşturup ekleyebilirsiniz.

İşlenmekte olan mevcut mağaza için yer kimliğini verilerinizden alın. Yer kimliği, öğenin hangi yeri göstereceğini kontrol etmek için kullanılır.

JavaScript'te PlaceDetailsCompactElement örneğini dinamik olarak oluşturun. Yeni bir PlaceDetailsPlaceRequestElement de oluşturulur, yer kimliği buna iletilir ve bu, PlaceDetailsCompactElement öğesine eklenir. Son olarak, öğenin göstereceği içeriği yapılandırmak için PlaceContentConfigElement kullanın.

Aşağıdaki işlev, gerekli Place UI Kit kitaplıklarının içe aktarıldığını ve bu işlevin çağrıldığı kapsamda kullanılabildiğini, storeData işlevine place_id değerinin iletildiğini varsayar.

Bu işlev öğeyi döndürür ve çağıran kod, öğeyi DOM'a eklemekten sorumludur.

function createPlaceDetailsCompactElement(storeData) {
    // Create the main details component
    const detailsCompact = new PlaceDetailsCompactElement();
    detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'

    // Specify the Place ID
    const placeRequest = new PlaceDetailsPlaceRequestElement();
    placeRequest.place = storeData.place_id;
    detailsCompact.appendChild(placeRequest);

    // Configure which content elements to display
    const contentConfig = new PlaceContentConfigElement();
    // For this example, we'll render media, rating, accessibility, and attribution:
    contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
    contentConfig.appendChild(new PlaceRatingElement());
    contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
    // Configure attribution
    const placeAttribution = new PlaceAttributionElement();
    placeAttribution.setAttribute('light-scheme-color', 'gray');
    placeAttribution.setAttribute('dark-scheme-color', 'gray');
    contentConfig.appendChild(placeAttribution);
    detailsCompact.appendChild(contentConfig);
    // Return the element
    return detailsCompact;
}

Yukarıdaki örnek kodda, öğe yer fotoğraflarını, yorum puanını ve erişilebilirlik bilgilerini gösterecek şekilde yapılandırılmıştır. Bu bölüm, diğer kullanılabilir içerik öğeleri eklenerek veya kaldırılarak özelleştirilebilir. Kullanılabilir tüm seçenekler için PlaceContentConfigElement dokümanına bakın.

Yer Ayrıntıları Kompakt Öğesi, CSS özel özellikleri aracılığıyla stil oluşturmayı destekler. Bu sayede, görünümünü (renkler, yazı tipleri vb.) uygulamanızın tasarımına uyacak şekilde özelleştirebilirsiniz. Bu özel özellikleri CSS dosyanıza uygulayın. Desteklenen CSS özellikleri için PlaceDetailsCompactElement ile ilgili referans belgelerine bakın.

Bu aşamada uygulamanızın nasıl görünebileceğine dair bir örnek:

resim

Mağaza bulucuyu geliştirme

Mağaza bulucu uygulamanız için sağlam bir temel oluşturdunuz. Şimdi de işlevselliğini genişletmenin ve daha da zengin, kullanıcı odaklı bir deneyim oluşturmanın çeşitli yollarını ele alalım.

Otomatik Tamamlama Ekleyin

Yer Otomatik Tamamlama ile bir arama girişi entegre ederek kullanıcıların mağaza arayacakları alanları bulma şeklini iyileştirin. Kullanıcılar bir adres, mahalle veya ilgi çekici yer yazıp bir öneri seçtiğinde haritayı otomatik olarak bu konuma ortalayacak şekilde programlayın. Bu işlem, yakındaki mağazaların güncellenmesini tetikler. Bunu, bir giriş alanı ekleyip Yer Otomatik Tamamlama işlevini bu alana ekleyerek yapabilirsiniz. Öneri seçildiğinde harita o noktaya ortalanabilir. Sonuçları operasyonel alanınıza göre yönlendirecek veya kısıtlayacak şekilde yapılandırmayı unutmayın.

Konumu algılama

Mevcut coğrafi konumlarını tespit etme işlevini uygulayarak özellikle mobil kullanıcılar için anında alaka düzeyi sunun. Tarayıcıdan konumlarını algılamak için izin aldıktan sonra haritayı otomatik olarak konumlarının merkezine alın ve en yakın mağazaları gösterin. Kullanıcılar, acil seçenekler ararken bu yakınımdaki özelliğine büyük değer verir. Konum erişimi isteğinde bulunmak için bir düğme veya ilk istem ekleyin.

Mesafeyi ve yol tarifini göster

Kullanıcılar ilgilendikleri bir mağazayı belirledikten sonra Routes API'yi entegre ederek yolculuklarını önemli ölçüde iyileştirin. Listelediğiniz her mağaza için kullanıcının mevcut konumuna veya aranan konuma olan mesafeyi hesaplayıp gösterin. Ayrıca, kullanıcının konumundan seçilen mağazaya bir rota oluşturmak için Routes API'yi kullanan bir düğme veya bağlantı sağlayın. Ardından bu rotayı haritanızda gösterebilir veya navigasyon için Google Haritalar'a bağlantı verebilirsiniz. Böylece, mağaza bulma işleminden mağazaya ulaşma işlemine sorunsuz bir şekilde geçiş yapabilirsiniz.

Bu uzantıları uygulayarak Google Haritalar Platformu'nun daha fazla özelliğinden yararlanabilir ve yaygın kullanıcı ihtiyaçlarını doğrudan karşılayan daha kapsamlı ve kullanışlı bir mağaza bulucu oluşturabilirsiniz.

Sonuç

Bu kılavuzda, etkileşimli bir mağaza bulucu oluşturmanın temel adımları gösterilmiştir. Maps JavaScript API'yi kullanarak kendi mağaza konumlarınızı haritada göstermeyi, görünür mağazaları görünüm alanı değişikliklerine göre dinamik olarak güncellemeyi ve en önemlisi, kendi mağaza verilerinizi Places UI Kit ile uyumlu şekilde göstermeyi öğrendiniz. Yer ayrıntıları öğesiyle birlikte yer kimlikleri de dahil olmak üzere mevcut mağaza bilgilerinizi kullanarak her bir konumunuz için zengin ve standartlaştırılmış ayrıntılar sunabilir, böylece kullanıcı dostu bir mağaza bulucu için sağlam bir temel oluşturabilirsiniz.

Gelişmiş konuma dayalı uygulamaları hızlı bir şekilde geliştirmek için güçlü ve bileşen tabanlı araçlar sunmak üzere Maps JavaScript API ve Places UI Kit'i deneyin. Bu özellikleri birleştirerek kullanıcılarınız için ilgi çekici ve bilgilendirici deneyimler oluşturabilirsiniz.

Katkıda bulunanlar

Henrik Valve | DevX Engineer