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

เมื่อตั้งค่า 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 เดียวกันในฟังก์ชันเรียกกลับที่ส่วนท้าย

    <!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 การเปลี่ยนแปลงข้อมูลเมตาจะทริกเกอร์เหตุการณ์ update ออบเจ็กต์ 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 เพื่อจัดการข้อผิดพลาดที่ไม่ได้คาดการณ์ไว้

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