Rota Genel Bakış API'sı

Route Overview API, DriverSDK üzerinde derlenmiş bir Son Mil Filo Çözümü ürünüdür. Tek seferlik getirme veya güncellemeler için bir işleyiciyi kullanarak sürekli olarak belirli bir araç için rota bilgilerini alabilirsiniz. Rotaya Genel Bakış API'si, aşağıdaki bilgi türlerini destekler:

  • Aracın durak konumları, seyahat süreleri, mesafeler dahil tam rota planı
  • Her bir durak arasındaki rota çoklu çizgi yolu.

Bu belgede, uygulamanızın API ile entegrasyon adımları açıklanmaktadır.

Ön koşullar

  • Android uygulamanızı DriverSDK v4.1.0 veya daha yüksek sürümünün alfa kanalını kullanarak çalıştırıyor olmanız gerekir. Alfa kanalı, Maven artifactId için transportation-driver-alpha kullanılarak kullanılabilir.
  • API, Fleet Engine tarafından Deliveryies API aracılığıyla sağlanan rota bilgilerini kullanır. Bu, DriverSDK (DeliveryDriverApi) üzerindeki API'ler aracılığıyla veya doğrudan Fleet Engine'e sağlanabilir.

Entegrasyon adımları

Bu bölümde, Android sürücü uygulamanızı API ile entegre etmek için gereken temel adımlar ele alınmaktadır. Bu talimatlar aşağıdaki varsayımlara sahiptir:

  • Driver SDK'sı ile entegre edilmiş mevcut bir Android uygulamanız
  • Uygulamanızda DeliveryDriverApi öğesini, bulabileceğiniz bir bağlam nesnesiyle başlattınız

Ayrıntılı bilgi için Android için Sürücü SDK'sını Kullanmaya Başlama bölümüne bakın.

0. Adım - Rota kurulumu

Fleet Engine'i zaten kurduysanız ve araç durakları ile teslimat görevleri oluşturabiliyorsanız bu adımı atlayabilirsiniz.

Durma ve görev bilgilerini Fleet Engine'e yüklemek için geçerli bir rotaya atanmış bir teslimat aracına ihtiyacınız vardır. Bunun nedeni, Route Overview API'nin verileri getirmek için geçerli rotalar gerektirmesidir. Geçerli rotalar bir dizi ara nokta ve duraktan oluşur ve bir durak yalnızca en az bir ilişkili görev olması durumunda mevcut olabilir. Daha fazla bilgi için Fleet Engine API entegrasyon kılavuzuna bakın.

1. adım - API'yi başlatma

İlişkili durak ve görevlerle geçerli bir rota oluşturduğunuzda, Rotaya Genel Bakış API'sini başlatabilirsiniz. Başlatma, Fleet Engine ve API arasındaki bağlantı için gerekli çerçeveyi sağlar. Rotaya Genel Bakış API, DriverSDK'da DeliveryDriverApi aracını ilk kullanıma hazırlamak için kullandığınız bağlam nesnesiyle başlatılmalıdır. Bunun nedeni, nesnenin daha önce DriverContext nesnenizde tanımlanan araç kimliğini temsil etmesidir. Aşağıdaki örnekte, RouteOverviewApi örneğinin nasıl oluşturulacağı gösterilmektedir.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

2. Adım - Aracı rota değişikliği etkinlikleri için kaydedin

API'yi başlattığınıza göre artık rotaya genel bakış özellikleriyle etkileşimde bulunmak için VehicleRouteOverview nesnesini kullanabilirsiniz. Bu işlem, uygulamanızın rota kurulumu sırasında sağladığınız rota bilgilerini kullanmasına olanak tanır. Etkinlik güncellemelerini ve rota alımını kolaylaştırmak için API etkinlik işleyicisini kullanın.

Araca atanan herhangi bir durağın yolu güncellendiğinde, bir durak yeniden düzenlendiğinde veya Fleet Engine GMR bilgilerini güncellediğinde bir rota değişikliği etkinliği gerçekleşir.


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

3. Adım - API'yi etkinleştirin

Artık rota bilgilerini kullanmaya hazır olduğunuza göre, araç etkinliklerine yanıt vermesi için API'yi etkinleştirmeniz gerekir. Ağ bant genişliğinin gereksiz şekilde kullanılmasını önlemek için API'nin devre dışı durumunda başlatıldığını unutmayın.

vehicleRouteOverview.setRouteOverviewEnabled(true);

false değeriyle aynı yöntemi çağırarak bu güncellemeleri istediğiniz zaman duraklatabilirsiniz.

4. Adım - Rotayı Google Haritası üzerinde çizin

Bir RouteToVehicleStop listesi aldıktan sonra bunu uygulamanızda kullanabilirsiniz. Örneğin, bir Google Haritası örneğinde rota çoklu çizgi yolunu çizebilirsiniz. Aşağıdaki kod snippet'i, harita görünümünde rota çoklu çizgisini çizen ve her bir durak konumunun üstüne işaretçiler ekleyen bir örneği göstermektedir.

    GoogleMap googleMap = … // Instance of the Map view you are using
    ImmutableList<RouteToVehicleStop> route = event.newRoute();

    PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
    for (RouteToVehicleStop stop : route) {
        routePolyline.addAll(stop.path());

        MarkerOptions marker =
            new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
        googleMap.addMarker(marker);
    }

    googleMap.addPolyline(routePolyline);
}

Rotaya genel bakış resmini gösteren ekran görüntüsü

Bu, sağdaki ekran görüntüsüne benzer bir görünümle sonuçlanır:

5. Adım - Rota anlık görüntüsünü alın

Uygulamanızın mevcut rota bilgilerinin anlık görüntüsünü almak için tek seferlik bir arama yapmasını istiyorsanız bu verileri almak için aşağıdaki yöntemi kullanabilirsiniz:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

Bunu, rota güncellemelerine etkinlik işleyiciler aracılığıyla abone olmak yerine yapabilirsiniz.

6. Adım: Temizleme

Uygulamanız artık rotaya genel bakış işlevine ihtiyaç duymuyorsa temizleme işlemini gerçekleştirdiğinizden emin olun. Temizleme yaparak uygulamanızda gereksiz bellek, işleme ve ağ tüketimini önlersiniz.

Belirli bir etkinlik işleyiciyi kaldırma

Belirli bir işleyici artık gerekli olmadığında etkinlik işleyiciyi kaldırmalısınız.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Tüm etkinlik işleyicileri temizle

Temizlik rutininiz kapsamında, tek seferde kaydedilen tüm farklı etkinlik işleyicileri kaldırabilirsiniz.

vehicleRouteOverview.clearEventListeners();

Rotaya Genel Bakış API'si örneğini temizle

Rotaya Genel Bakış artık gerekli olmadığında veya takip edilen aracın kimliği değiştiğinde dahili referansları temizlemek için bu API'yi çağırabilirsiniz.

vehicleRouteOverview.clearInstance();