Gönderimi takip etme

Planlanmış görevler için JavaScript Tüketici SDK'sını ayarladığınıza göre, tüketici uygulamanızla bir gönderimi takip etmeye hazırsınız. Bu dokümanda, bu süreçteki aşağıdaki temel adımlar ele alınmaktadır:

  • Haritayı başlatma ve paylaşılan yolculuğu görüntüleme
  • Yolculuğun ilerleme durumunu güncelleme ve takip etme
  • Gönderiyi takip etmeyi bırakma
  • Gönderi takip hatalarını giderme

Harita oluşturma

Web uygulamanızda bir gönderimin alınmasını veya teslim edilmesini takip etmek için gönderinizi izlemeye başlamak üzere bir harita yüklemeniz ve Consumer SDK'sını örneklemeniz gerekir. Yeni bir harita yükleyebilir veya mevcut bir haritayı kullanabilirsiniz. Ardından, harita görünümünün izlenen öğenin konumuna karşılık gelmesi için Tüketici SDK'sını örneklemek üzere ilklendirme işlevini kullanırsınız.

Google Haritalar JavaScript API'yi kullanarak yeni bir harita yükleme

Yeni bir harita oluşturmak için Google Maps JavaScript API'yi web uygulamanıza yükleyin. Aşağıdaki örnekte, Google Maps JavaScript API'nin nasıl yükleneceği, SDK'nın nasıl etkinleştirileceği ve başlatma kontrolünün nasıl tetikleneceği gösterilmektedir.

  • callback parametresi, API yüklendikten sonra initMap işlevini çalıştırır.
  • defer özelliği, API yüklenirken tarayıcının sayfanızı oluşturmaya devam etmesini sağlar.

Tüketici SDK'sını örneklemek için initMap işlevini kullanın. Örneğin:

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

Mevcut bir haritayı yükleme

Google Haritalar JavaScript API tarafından oluşturulmuş mevcut bir haritayı (ör. halihazırda kullandığınız bir harita) da yükleyebilirsiniz.

Örneğin, aşağıdaki HTML kodunda tanımlandığı şekilde bir işaretçi gösterilen standart bir google.maps.Map öğesi olan bir web sayfanız olduğunu varsayalım. Bu örnekte, sonunda geri çağırma işlevinde aynı initMap işlevi kullanılarak haritanız gösterilmektedir:

    <!DOCTYPE html>
    <html>
      <head>
        <style>
           /* Set the size of the div element that contains the map */
          #map {
            height: 400px;  /* The height is 400 pixels */
            width: 100%;  /* The width is the width of the web page */
           }
        </style>
      </head>
      <body>
        <h3>My Google Maps Demo</h3>
        <!--The div element for the map -->
        <div id="map"></div>
        <script>
        // Initialize and add the map
        function initMap() {
          // The location of Pier 39 in San Francisco
          var pier39 = {lat: 37.809326, lng: -122.409981};
          // The map, initially centered at Mountain View, CA.
          var map = new google.maps.Map(document.getElementById('map'));
          map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});

          // The marker, now positioned at Pier 39
          var marker = new google.maps.Marker({position: pier39, map: map});
        }
        </script>
        <!-- Load the API from the specified URL.
           * The defer attribute allows the browser to render the page while the API loads.
           * The key parameter contains your own API key.
           * The callback parameter executes the initMap() function.
        -->
        <script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
        </script>
      </body>
    </html>

Gönderim konumu sağlayıcısı oluşturma

Fleet Engine'dan veri almaya başlamak için daha önce tanımladığınız yetkilendirme jetonu alıcısıyla birlikte gönderi konumu sağlayıcıyı kullanın.

Bu örneklerde, konum sağlayıcının nasıl oluşturulacağı gösterilmektedir.

JavaScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

TypeScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

Paylaşılan yolculuğu görüntüleme

Planlanmış bir görevin ilerleme durumunu görüntülemek için görünümünü başlatın. Bu işlem, haritanın çerçevesini izlenen yolculuğun konumuna karşılık gelecek şekilde ayarlar. Ardından, Tüketici SDK'sı, Fleet Engine'dan bilgileri aldıktan sonra ilerleme durumunu sağlar.

İpuçları:

  1. Sayfanızda harita görünümünü içeren bir <div> öğesi bulunduğundan emin olun. Aşağıdaki örnekte, <div> öğesi map_canvas olarak adlandırılmıştır.

  2. Fleet Engine'ın, izlenen yolculuklar için uyguladığı varsayılan görünürlük kurallarına dikkat edin. Etkin araç sevkiyat ve planlanmış durak görevleri için görünürlük kurallarını da yapılandırabilirsiniz. Görevleri yapılandırma kılavuzundaki Görev görünürlüğünü özelleştirme bölümüne bakın.

Bu örneklerde, bir harita görünümünün nasıl başlatılacağı gösterilmektedir.

JavaScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts as soon as this is set.
  locationProvider.trackingId = 'your-tracking-id';

  // Give the map an initial viewport to allow it to
  // initialize; otherwise the 'ready' event above may
  // not fire. The user also has access to the mapView
  // object to customize as they wish.
  mapView.map.setCenter({lat: 37.2, lng: -121.9});
  mapView.map.setZoom(14);
}

TypeScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
   // Any undefined styling options will use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts as soon as this is set.
  locationProvider.trackingId = 'your-tracking-id';

  // Give the map an initial viewport to allow it to
  // initialize; otherwise the 'ready' event above may
  // not fire. The user also has access to the mapView
  // object to customize as they wish.
  mapView.map.setCenter({lat: 37.2, lng: -121.9});
  mapView.map.setZoom(14);
}

Gönderim ilerleme durumunu güncelleme

Etkinlikleri dinleyebilir ve yolculuk ilerledikçe gönderim ilerleme durumunu güncelleyebilirsiniz. taskTrackingInfo nesnesinden meta bilgileri almak için konum sağlayıcıyı kullanın. Meta bilgilerde yapılan değişiklikler bir güncelleme etkinliği tetikler. taskTrackingInfo nesnesi aşağıdakileri sağlar:

  • TVS
  • Kalan durak sayısı
  • Teslim alma veya teslimat noktasına kalan mesafe

Aşağıdaki örnekte, bu değişiklik etkinliklerinin nasıl dinleneceği gösterilmektedir.

JavaScript

locationProvider.addListener('update', e => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

Birden fazla görev için ölçütleri görüntüleme

Planlanmış görevler için tüketici SDK'sı, haritada takip kimliği başına yalnızca bir görev gösterir. Bununla birlikte, genellikle belirli bir kargo ürününe bir izleme kimliği atarsınız. Bu izleme kimliği, ürün sisteminizde yolculuk boyunca ürünle ilişkili kalır. Yani tek bir takip kimliği, birden fazla görevle ilişkilendirilebilir. Örneğin, aynı paket için teslimat görevinin ardından teslim alma görevi veya bir paket için birden fazla başarısız gönderim görevi.

Fleet Engine, bu durumu ele almak için aşağıdaki tabloda gösterilen görevleri görüntüleme ölçütlerini uygular.

Görev ölçütleri Sonuç
Arama görevlerini açma
Tam olarak bir tane var Görevi gösterme
Birden fazla var Hata oluşturma
Kapalı teslim alma görevleri
Tam olarak bir tane var Görevi gösterme
Birden fazla var (bazıları sonuç zamanlarıyla) Görevi en son sonuç zamanıyla göster
Birden fazla var (sonuç süreleri olmayan) Hata oluşturma
Yayınlama görevlerini açma
Tam olarak bir tane var Görevi gösterme
Birden fazla var Hata oluşturma
Kapalı yayın görevleri
Tam olarak bir tane var Görevi gösterme
Birden fazla var (bazıları sonuç zamanlarıyla) Görevi en son sonuç zamanıyla göster
Birden fazla var (sonuç süreleri olmayan) Hata oluşturma

Gönderiyi takip etmeyi bırakma

Bir gönderim yolculuğu tamamlandığında veya iptal edildiğinde tüketici uygulamanız, takip kimliğini ve konum sağlayıcıyı harita görünümünden kaldırarak gönderimi takip etmeyi bırakmalıdır. Ayrıntılar için aşağıdaki bölümlere bakın.

İzleme kimliğini kaldırma

Konum sağlayıcının gönderiyi izlemesini durdurmak için takip kimliğini konum sağlayıcıdan kaldırın. Aşağıdaki örneklerde bunun nasıl yapılacağı gösterilmektedir.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Konum sağlayıcıyı harita görünümünden kaldırma

Aşağıdaki örnekte, bir konum sağlayıcının harita görünümünden nasıl kaldırılacağı gösterilmektedir.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Gönderi takip hatalarını giderme

Gönderi bilgileri istenirken eşzamansız olarak ortaya çıkan hatalar hata etkinliklerini tetikler. Aşağıdaki örnekte, hataları işlemek için bu etkinliklerin nasıl dinleneceği gösterilmektedir.

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

Not: Beklenmedik hataları ele almak için kitaplık çağrılarını try...catch bloklarına sarmalayın.

Sırada ne var?