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

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

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

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

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

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

หากต้องการสร้างแผนที่ใหม่ ให้โหลด Google Maps JavaScript API ในเว็บแอปของคุณ ตัวอย่างต่อไปนี้แสดงวิธีโหลด Google Maps JavaScript API, เปิดใช้ 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 มีข้อมูลต่อไปนี้

  • ETA
  • จำนวนป้ายจอดรถที่เหลือ
  • ระยะทางที่เหลือก่อนรับหรือนำส่ง

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

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 จะใช้เกณฑ์ในการแสดงงานดังที่แสดงในตารางต่อไปนี้

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

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

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

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

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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 เพื่อจัดการกับข้อผิดพลาดที่ไม่คาดคิด

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