Places UI Kit ile mağaza bulucu

Hedef

Bu belgede, Google Haritalar Platformu'nu, özellikle de Maps JavaScript API'yi ve Places UI Kit'i (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 bilgilerini görüntülemeyi öğreneceksiniz.

Ön koşullar

Aşağıdaki konular hakkında bilgi sahibi 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örüntülemek için kullanılır.
• Places UI Kit: Kullanıcı arayüzünde mağazalarınızla ilgili bilgileri görüntülemek 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ğinizden ve Gelişmiş İşaretçiler ile Places UI Kit için gerekli kitaplıkları içe aktardığınızdan emin olun. Bu dokümanda ayrıca HTML, CSS ve JavaScript dahil olmak üzere web geliştirme konusunda bilgi sahibi olduğunuz varsayılır.

İlk kurulum

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

Bir sayfaya harita eklemenin iki yolu vardır:

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

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

Mağaza Konumlarını Yükleme ve Gösterme

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

Mağaza konumlarınızın yer kimliklerini henüz almadıysanız bunları almanın çeşitli yolları vardır. Daha fazla bilgi için Yer Kimliği belgelerine bakın.

stores.json dosyanızdaki örnek bir mağaza ayrıntıları girişi şu şekilde görünebilir. Ad, Konum (enlem/boylam) ve Yer Kimliği alanları vardır. Mağazanın çalışma saatlerini içeren bir nesne var (kısaltılmış). Ayrıca mağaza konumunun özel özelliklerini tanımlamaya yardımcı olan iki boole değeri 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 alın ve haritada her biri için bir raptiye gösterin.

Bunun nasıl yapılacağına dair bir örnek aşağıda verilmiştir. 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ı temsil eden raptiyeleri haritada gösterdikten sonra, mağazalarınızla ilgili ayrıntıları göstermek için HTML ve CSS kullanarak bir kenar çubuğu oluşturun.

Mağaza bulma aracınızın bu aşamada nasıl görünebileceğine dair bir örnek aşağıda verilmiştir:

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üntü alanı) olduğunda kenar çubuğunda gösterecek şekilde güncelleyin. Bu işlem, harita görüntüleme alanı değişikliklerini dinlemeyi, bu etkinlikleri geciktirmeyi ve ardından yalnızca gerekli işaretçileri yeniden çizmeyi içerir.

Haritanın boşta etkinliğine bir etkinlik işleyici ekleyin. Bu etkinlik, kaydırma veya yakınlaştırma işlemleri tamamlandıktan sonra tetiklenir ve 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 bir debounce işlevini çağırır. Debounce işlevi kullanmak, işaretçi güncelleme mantığınızın yalnızca kullanıcı haritayla etkileşimi kısa bir süre için durdurduktan 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, örnek bir debounce işlevidir. Bu işlev, boşta dinleyicisinde 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 edilir bir gecikme eklemeden haritanın hareketinin durmasını beklemek için yeterlidir. Bu zaman aşımı süresi dolduğunda, iletilen işlev çağrılır (bu örnekte updateMarkersInView).

updateMarkersInView işlevi aşağıdaki işlemleri gerçekleştirmelidir:

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 mağaza ayrıntılarını kenar çubuğunda göstermek için kod yazın.

Yer Ayrıntıları öğesini kullanarak zengin yer ayrıntılarını görüntüleme

Bu aşamada uygulama tüm mağaza konumlarını gösterir ve kullanıcılar bunları harita görüntüleme alanına göre filtreleyebilir. Bu deneyimi daha da iyileştirmek için Yer Ayrıntıları öğesi kullanılarak her mağazayla ilgili fotoğraflar, yorumlar ve erişilebilirlik bilgileri gibi zengin ayrıntılar eklenir. Bu örnekte özellikle Yer Ayrıntıları Compact Element kullanılmıştır.

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

Uygulamaya Yer Ayrıntıları En Yüksek Yoğunluklu Öğeyi entegre etme

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

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

JavaScript'te dinamik olarak bir PlaceDetailsCompactElement örneği 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 Places UI Kit kitaplıklarının içe aktarıldığını ve bu işlevin çağrıldığı kapsamda kullanılabildiğini, işleve iletilen storeData değerinin ise place_id içerdiğini varsayar.

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

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, mevcut diğer içerik öğeleri eklenerek veya kaldırılarak özelleştirilebilir. Mevcut tüm seçenekler için PlaceContentConfigElement belgelerine bakın.

Yer Ayrıntıları En Yüksek öğ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 referans belgelerine bakın.

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

Mağaza bulucuyu iyileştirme

Mağaza bulma uygulamanız için sağlam bir temel oluşturdunuz. Şimdi, işlevselliğini genişletmenin ve daha zengin, daha kullanıcı odaklı bir deneyim oluşturmanın birkaç yolunu düşünün.

Otomatik Tamamlama Ekleyin

Arama girişini Yer Adı Otomatik Tamamlama ile entegre ederek kullanıcıların mağaza arayacakları alanları bulma şeklini iyileştirin. Kullanıcılar bir adres, mahalle veya önemli yer yazıp bir öneri seçtiğinde haritayı otomatik olarak bu konumu merkeze alacak şekilde programlayın. Bu işlem, yakındaki mağazaların güncellenmesini tetikler. Bunu yapmak için bir giriş alanı ekleyin ve Yer Adı Otomatik Tamamlama işlevini bu alana ekleyin. Bir öneri seçildiğinde harita bu noktaya ortalanabilir. Sonuçları faaliyet bölgenize göre yönlendirecek veya kısıtlayacak şekilde yapılandırmayı unutmayın.

Konumu algıla

Özellikle mobil kullanıcılar için mevcut coğrafi konumlarını algılama işlevini uygulayarak anında alaka düzeyi sunun. Kullanıcının konumunu tespit etmek için tarayıcı izni aldıktan sonra haritayı otomatik olarak kullanıcının konumuna ortalayın ve en yakın mağazaları gösterin. Kullanıcılar, acil seçenekler ararken bu Yakınımda özelliğine çok değer veriyor. Konum erişimi istemek için bir düğme veya ilk istem ekleyin.

Mesafe ve yol tarifini gösterme

Kullanıcı ilgilendiği bir mağazayı belirledikten sonra Routes API'yi entegre ederek yolculuğunu ö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 rota oluşturmak için Routes API'yi kullanan bir düğme veya bağlantı ekleyin. Ardından bu rotayı haritanızda gösterebilir veya navigasyon için Google Haritalar'a bağlantı verebilirsiniz. Böylece, mağaza bulma aşamasından mağazaya ulaşma aşamasına sorunsuz bir geçiş sağlayabilirsiniz.

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 bulma aracı 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üntü alanındaki değişikliklere göre dinamik olarak güncellemeyi ve en önemlisi, kendi mağaza verilerinizi Places UI Kit'e uygun şekilde göstermeyi öğrendiniz. Yer Kimlikleri de dahil olmak üzere mevcut mağaza bilgilerinizi Yer Ayrıntıları öğesiyle kullanarak her bir konumunuz için zengin ve standartlaştırılmış ayrıntılar sunabilir, böylece kullanıcı dostu bir mağaza bulma aracı için sağlam bir temel oluşturabilirsiniz.

Gelişmiş konuma dayalı uygulamaları hızlı bir şekilde geliştirmek için güçlü, bileşen tabanlı araçlar sunan 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 Mühendisi