ติดตามการจัดส่ง

เมื่อตั้งค่า JavaScript Consumer SDK สำหรับงานที่กำหนดเวลาไว้แล้ว คุณก็พร้อมที่จะติดตามการจัดส่งด้วยแอปผู้บริโภค เอกสารนี้ครอบคลุมขั้นตอนสำคัญต่อไปนี้ในกระบวนการนี้

  • เริ่มต้นแผนที่และแสดงการเดินทางที่แชร์
  • อัปเดตและติดตามความคืบหน้าของเส้นทาง
  • หยุดติดตามการจัดส่ง
  • จัดการข้อผิดพลาดในการติดตามการจัดส่ง

ตั้งค่าแผนที่

หากต้องการติดตามการรับหรือการจัดส่งสินค้าในเว็บแอป คุณต้องโหลดแผนที่และสร้างอินสแตนซ์ Consumer SDK เพื่อเริ่มติดตามการจัดส่ง คุณสามารถโหลดแผนที่ใหม่ หรือใช้แผนที่ที่มีอยู่ก็ได้ จากนั้นคุณจะใช้ฟังก์ชันการเริ่มต้นเพื่อสร้างอินสแตนซ์ Consumer SDK เพื่อให้มุมมองแผนที่สอดคล้องกับตำแหน่งของรายการที่ติดตาม

โหลดแผนที่ใหม่โดยใช้ Google Maps JavaScript API

หากต้องการสร้างแผนที่ใหม่ ให้โหลด Maps JavaScript API ของ Google ในเว็บแอป ตัวอย่างต่อไปนี้แสดงวิธีโหลด Maps JavaScript API ของ Google, เปิดใช้ SDK และเรียกใช้การตรวจสอบการเริ่มต้น

  • พารามิเตอร์ callback จะเรียกใช้ฟังก์ชัน initMap หลังจากที่ API โหลดแล้ว
  • แอตทริบิวต์ defer ช่วยให้เบราว์เซอร์แสดงผลส่วนที่เหลือของหน้าเว็บต่อไปได้ขณะที่ API โหลดอยู่

ใช้ฟังก์ชัน initMap เพื่อสร้างอินสแตนซ์ Consumer SDK เช่น

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

โหลดแผนที่ที่มีอยู่

นอกจากนี้ คุณยังโหลดแผนที่ที่มีอยู่ซึ่งสร้างโดย Google Maps JavaScript API ได้ด้วย เช่น แผนที่ที่คุณใช้อยู่แล้ว

ตัวอย่างเช่น สมมติว่าคุณมีหน้าเว็บที่มีเอนทิตี google.maps.Map มาตรฐานซึ่งมีเครื่องหมายแสดงอยู่ตามที่กำหนดไว้ในโค้ด HTML ต่อไปนี้ โค้ดนี้จะแสดงแผนที่โดยใช้ฟังก์ชัน initMap เดียวกันใน Callback ที่ส่วนท้าย

    <!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>

สร้างอินสแตนซ์ผู้ให้บริการตำแหน่งการจัดส่ง

ใช้ผู้ให้บริการตำแหน่งการจัดส่งร่วมกับเครื่องมือดึงข้อมูลโทเค็นการให้สิทธิ์ที่คุณกำหนดไว้ก่อนหน้านี้เพื่อเริ่มรับข้อมูลจาก Fleet Engine

ตัวอย่างเหล่านี้แสดงวิธีสร้างอินสแตนซ์ผู้ให้บริการตำแหน่ง

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
  });

แสดงเส้นทางที่แชร์

หากต้องการแสดงความคืบหน้าของงานที่กำหนดเวลาไว้ ให้เริ่มต้นมุมมองของงาน ซึ่งจะตั้งค่าเฟรมสำหรับแผนที่ให้สอดคล้องกับตำแหน่งสำหรับการเดินทางที่ติดตาม จากนั้น Consumer SDK จะแสดงความคืบหน้าหลังจากได้รับข้อมูลจาก Fleet Engine

เคล็ดลับ

  1. ตรวจสอบว่าหน้าเว็บมีองค์ประกอบ <div> ที่มีมุมมองแผนที่ ในตัวอย่างต่อไปนี้ องค์ประกอบ <div> มีชื่อว่า map_canvas

  2. โปรดคำนึงถึงกฎการแสดงผลเริ่มต้นที่ Fleet Engine ใช้กับการเดินทางที่ติดตาม นอกจากนี้ คุณยังกำหนดค่ากฎระดับการเข้าถึงสำหรับงานการจัดส่งด้วยยานพาหนะที่ใช้งานอยู่และงานการหยุดที่กำหนดเวลาไว้ได้ด้วย ดูหัวข้อปรับแต่งระดับการเข้าถึงงานในคู่มือกำหนดค่างาน

ตัวอย่างเหล่านี้แสดงวิธีเริ่มต้นมุมมองแผนที่

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);
}

อัปเดตความคืบหน้าของการจัดส่ง

คุณสามารถฟังเหตุการณ์และอัปเดตความคืบหน้าของการจัดส่งเมื่อการเดินทางคืบหน้าได้ ใช้ผู้ให้บริการตำแหน่งเพื่อดึงข้อมูลเมตาจากออบเจ็กต์ taskTrackingInfo การเปลี่ยนแปลงข้อมูลเมตาจะทริกเกอร์เหตุการณ์อัปเดต ออบเจ็กต์ taskTrackingInfo มีข้อมูลต่อไปนี้

  • เวลาถึงโดยประมาณ
  • จำนวนจุดแวะพักที่เหลืออยู่
  • ระยะทางที่เหลือก่อนรับหรือส่งสินค้า

ตัวอย่างต่อไปนี้แสดงวิธีฟังเหตุการณ์การเปลี่ยนแปลงเหล่านี้

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);
});

แสดงเกณฑ์สำหรับงานหลายรายการ

Consumer SDK สำหรับงานที่กำหนดเวลาไว้จะแสดงงานเพียง 1 งานต่อรหัสติดตามบนแผนที่ อย่างไรก็ตาม โดยปกติแล้วคุณจะกำหนดรหัสติดตาม 1 รหัสให้กับสินค้าที่จัดส่งที่เฉพาะเจาะจง ซึ่งจะยังคงเชื่อมโยงกับสินค้าตลอดการเดินทางในระบบของคุณ ซึ่งหมายความว่ารหัสติดตามเดียวอาจเชื่อมโยงกับงานหลายรายการ เช่น งานรับสินค้าตามด้วยงานนำส่งสำหรับพัสดุเดียวกัน หรือการจัดส่งพัสดุไม่สำเร็จหลายครั้ง

เพื่อจัดการกับสถานการณ์นี้ Fleet Engine จะใช้เกณฑ์ในการแสดงงานตามที่แสดงในตารางต่อไปนี้

เกณฑ์ของงาน ผลลัพธ์
เปิดงานรับสินค้า
มีอยู่ 1 รายการพอดี แสดงงาน
มีหลายรายการ ข้อผิดพลาดในการสร้าง
งานรับสินค้าที่ปิดแล้ว
มีอยู่ 1 รายการพอดี แสดงงาน
มีหลายรายการ (บางรายการมีเวลาที่เกิดผลลัพธ์) แสดงงานที่มีเวลาผลลัพธ์ล่าสุด
มีหลายรายการ (ไม่มีรายการใดที่มีเวลาผลลัพธ์) ข้อผิดพลาดในการสร้าง
เปิดงานการนำส่ง
มีอยู่ 1 รายการพอดี แสดงงาน
มีหลายรายการ ข้อผิดพลาดในการสร้าง
งานการแสดงโฆษณาที่ปิดแล้ว
มีอยู่ 1 รายการพอดี แสดงงาน
มีหลายรายการ (บางรายการมีเวลาที่เกิดผลลัพธ์) แสดงงานที่มีเวลาผลลัพธ์ล่าสุด
มีหลายรายการ (ไม่มีรายการใดที่มีเวลาผลลัพธ์) ข้อผิดพลาดในการสร้าง

หยุดติดตามการจัดส่ง

เมื่อการเดินทางของการจัดส่งเสร็จสมบูรณ์หรือถูกยกเลิก แอปผู้บริโภคควรหยุดติดตามการจัดส่งโดยนำรหัสติดตามและผู้ให้บริการตำแหน่งออกจากมุมมองแผนที่ โปรดดูรายละเอียดที่หัวข้อด้านล่าง

นำรหัสติดตามออก

หากต้องการหยุดไม่ให้ผู้ให้บริการตำแหน่งติดตามการจัดส่ง ให้นำรหัสติดตามออกจากผู้ให้บริการตำแหน่ง ตัวอย่างต่อไปนี้แสดงวิธีดำเนินการ

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

นำผู้ให้บริการตำแหน่งออกจากมุมมองแผนที่

ตัวอย่างต่อไปนี้แสดงวิธีนำผู้ให้บริการตำแหน่งออกจากมุมมองแผนที่

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

จัดการข้อผิดพลาดในการติดตามการจัดส่ง

ข้อผิดพลาดที่เกิดขึ้นแบบอะซิงโครนัสจากการขอข้อมูลการจัดส่งจะทริกเกอร์เหตุการณ์ error ตัวอย่างต่อไปนี้แสดงวิธีฟังเหตุการณ์เหล่านี้เพื่อจัดการข้อผิดพลาด

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);
});

หมายเหตุ: อย่าลืมรวมการเรียกใช้ไลบรารีไว้ในบล็อก try...catch เพื่อจัดการข้อผิดพลาดที่ไม่คาดคิด

ขั้นตอนถัดไป