ติดตามการจัดส่งด้วยไลบรารีการติดตามการจัดส่ง JavaScript

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

คอมโพเนนต์

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

มุมมองแผนที่การติดตามการจัดส่ง

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

ผู้ให้บริการสถานที่จัดส่ง

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

คุณใช้ผู้ให้บริการสถานที่จัดส่งเพื่อติดตามสิ่งต่อไปนี้ได้

  • สถานที่รับหรือจัดส่งของการจัดส่ง
  • ตำแหน่งและเส้นทางของรถนำส่ง

ออบเจ็กต์ตำแหน่งที่ติดตาม

ผู้ให้บริการตำแหน่งจะติดตามตำแหน่งของวัตถุ เช่น ยานพาหนะและจุดหมาย

ตำแหน่งปลายทาง

สถานที่จุดหมายคือสถานที่ที่การเดินทางสิ้นสุด การติดตามการจัดส่ง จะเป็นตำแหน่งที่วางแผนไว้

ตำแหน่งของรถ

ตำแหน่งของรถคือตำแหน่งของยานพาหนะที่ติดตาม โดยอาจรวมเส้นทางสำหรับยานพาหนะด้วยก็ได้

ตัวดึงข้อมูลโทเค็นการตรวจสอบสิทธิ์

หากต้องการควบคุมการเข้าถึงข้อมูลตำแหน่งที่จัดเก็บไว้ใน Fleet Engine คุณต้องใช้บริการสร้างข้อมูลของ JSON Web Token (JWT) สำหรับ Fleet Engine บนเซิร์ฟเวอร์ของคุณ จากนั้นใช้ตัวดึงข้อมูลโทเค็นการตรวจสอบสิทธิ์เป็นส่วนหนึ่งของเว็บแอปพลิเคชันโดยใช้ไลบรารีการแชร์เส้นทาง JavaScript เพื่อตรวจสอบสิทธิ์การเข้าถึงข้อมูลตำแหน่ง

ตัวเลือกการจัดรูปแบบ

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

ควบคุมการเปิดเผยสถานที่ที่ติดตาม

ส่วนนี้จะอธิบายการควบคุมการมองเห็นวัตถุที่ติดตามบนแผนที่ กฎเหล่านี้ใช้กับออบเจ็กต์ 2 หมวดหมู่ดังนี้

  • เครื่องหมายระบุตำแหน่ง
  • ข้อมูลงาน

การเปิดเผยเครื่องหมายตำแหน่ง

เครื่องหมายระบุตำแหน่งทั้งหมดสำหรับต้นทางและจุดหมายจะแสดงบนแผนที่เสมอ เช่น สถานที่นำส่งสำหรับจัดส่งจะแสดงในแผนที่เสมอ โดยไม่คำนึงถึงสถานะของการนำส่ง

ระดับการเข้าถึงข้อมูลงาน

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

  • งานที่ไม่พร้อมใช้งาน -- คุณไม่สามารถปรับแต่งการแสดงผลสำหรับงานเหล่านี้
  • งานในยานพาหนะที่ใช้งานอยู่ -- คุณสามารถปรับแต่งประเภทงานเหล่านี้ได้
  • งานในรถยนต์ที่ไม่ได้ใช้งาน -- คุณไม่สามารถปรับแต่งระดับการเข้าถึงสำหรับงานเหล่านี้

งานที่ไม่พร้อมใช้งาน

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

งานเกี่ยวกับยานพาหนะที่คล่องตัว

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

  • เส้นประกอบเส้นทาง
  • เวลาถึงโดยประมาณ
  • เวลาที่ใช้ทำงานเสร็จโดยประมาณ
  • ระยะทางการขับรถที่เหลืออยู่ไปยังงาน
  • จำนวนป้ายที่เหลือ
  • ตำแหน่งของรถ

คุณปรับแต่งการกำหนดค่าระดับการเข้าถึงเป็นรายงานได้โดยตั้งค่า TaskTrackingViewConfig ในงานเมื่อสร้างหรืออัปเดตงานภายใน Fleet Engine การดำเนินการนี้จะสร้างกฎเวลาที่องค์ประกอบข้อมูลแต่ละรายการพร้อมใช้งาน ซึ่งอาจขึ้นอยู่กับเกณฑ์ต่อไปนี้ (เรียกว่าตัวเลือกระดับการเข้าถึงด้านล่าง)

  • จำนวนป้ายที่เหลือ
  • ระยะเวลาที่จะถึงโดยประมาณ
  • ระยะทางขับรถที่เหลือ
  • แสดงเสมอ
  • ไม่แสดง

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

ตัวอย่างการปรับแต่งมีดังนี้ กฎของการปรับแต่งดังกล่าวมีดังนี้

  • แสดงเส้นประกอบของเส้นทางหากยานพาหนะอยู่ในช่วง 3 ป้าย
  • แสดงเวลาถึงโดยประมาณหากระยะทางการขับรถที่เหลืออยู่น้อยกว่า 5,000 เมตร
  • ไม่ต้องแสดงจำนวนการหยุดพักที่เหลืออยู่
  • ช่องแต่ละช่องจะยังคงมีการแสดงผลโดยค่าเริ่มต้นเมื่อยานพาหนะอยู่ภายในระยะ 5 จุดของงาน
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

คุณยังปรับแต่งการกำหนดค่าระดับการเข้าถึงเริ่มต้นสำหรับโปรเจ็กต์ได้โดยติดต่อทีมสนับสนุน

กฎการแสดงเส้นตารางและตำแหน่งยานพาหนะ:

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

ต้องปฏิบัติตามกฎเหล่านี้เพื่อระบุชุดค่าผสมโพลีไลน์บนเส้นทาง / ตำแหน่งของยานพาหนะที่ถูกต้อง

  • เมื่อโพลีไลน์ของเส้นทางและตำแหน่งยานพาหนะมีตัวเลือกระดับการเข้าถึงเหมือนกัน ดังนี้

    • หากตัวเลือกการเปิดเผยคือจำนวนการหยุด ระยะเวลาจนถึงเวลาถึงโดยประมาณ หรือระยะทางการขับขี่ที่เหลือ เส้นประกอบของเส้นทางต้องระบุค่าที่น้อยกว่าหรือเท่ากับค่าที่ตั้งไว้สำหรับตัวเลือกการเปิดเผยนี้สำหรับตำแหน่งยานพาหนะ ตัวอย่างมีดังต่อไปนี้
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    
    • หากโพลีไลน์ของเส้นทางมีตัวเลือกการแสดงผลที่มองเห็นได้เสมอ ตำแหน่งของยานพาหนะจะต้องมีตัวเลือกระดับการเข้าถึงที่มองเห็นได้เสมอ
    • หากตำแหน่งของยานพาหนะมีตัวเลือกการเปิดเผยแบบมองไม่เห็น เส้นประกอบเส้นทาง จะต้องมีตัวเลือกการเปิดเผยแบบมองไม่เห็นด้วย
  • เมื่อโพลีไลน์และตำแหน่งยานพาหนะมีตัวเลือกการเปิดเผยแตกต่างกัน ตำแหน่งของรถจะแสดงก็ต่อเมื่อตัวเลือกการเปิดเผยทั้ง 2 อย่างตรงกันเท่านั้น

    ตัวอย่างมีดังต่อไปนี้

    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingDrivingDistanceMetersThreshold": 3000
      },
    }
    

    ในตัวอย่างนี้ ตำแหน่งของรถจะปรากฏต่อเมื่อจำนวนป้ายจอดรถที่เหลือมีอย่างน้อย 3 และระยะทางขับรถที่เหลือมีระยะทางอย่างน้อย 3, 000 เมตร

เริ่มต้นใช้งานไลบรารีการแชร์เส้นทาง JavaScript

ก่อนใช้ไลบรารีการแชร์เส้นทาง JavaScript โปรดทำความคุ้นเคยกับ Fleet Engine และการรับคีย์ API

หากต้องการติดตามการจัดส่ง ให้สร้างการอ้างสิทธิ์รหัสติดตามก่อน

สร้างการอ้างสิทธิ์รหัสติดตาม

หากต้องการติดตามการจัดส่งโดยใช้ผู้ให้บริการสถานที่จัดส่ง ให้สร้าง JSON Web Token (JWT) ที่มีการอ้างสิทธิ์รหัสติดตาม

หากต้องการสร้างเพย์โหลด JWT ให้เพิ่มการอ้างสิทธิ์เพิ่มเติมในส่วนการให้สิทธิ์ด้วย trackingid ที่สำคัญ กำหนดค่าเป็นรหัสติดตามการจัดส่ง

ตัวอย่างต่อไปนี้แสดงวิธีสร้างโทเค็นเพื่อการติดตามด้วยรหัสติดตาม

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "trackingid": "tid_54321",
   }
}

สร้างตัวดึงข้อมูลโทเค็นการตรวจสอบสิทธิ์

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

ตัวดึงข้อมูลต้องแสดงผลโครงสร้างข้อมูลที่มี 2 ช่องซึ่งอยู่ใน "คำสัญญา" ดังนี้

  • สตริง token
  • หมายเลข expiresInSeconds โทเค็นจะหมดอายุภายในช่วงเวลานี้หลังจากการดึงข้อมูล

ไลบรารีการติดตามการจัดส่งของ JavaScript จะขอโทเค็นผ่านตัวดึงข้อมูลโทเค็นการตรวจสอบสิทธิ์เมื่อเป็นไปตามเงื่อนไขข้อใดข้อหนึ่งต่อไปนี้

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

ไม่เช่นนั้น ไลบรารีจะใช้โทเค็นที่ออกให้ก่อนหน้านี้ ยังใช้งานได้อยู่และจะไม่เรียกใช้ตัวดึงข้อมูล

ตัวอย่างต่อไปนี้แสดงวิธีสร้างตัวดึงข้อมูลโทเค็นการตรวจสอบสิทธิ์

JavaScript

function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
  };
}

เมื่อคุณใช้ปลายทางฝั่งเซิร์ฟเวอร์ในการสร้างโทเค็น โปรดคำนึงถึงสิ่งต่อไปนี้

  • ปลายทางต้องแสดงผลเวลาหมดอายุสำหรับโทเค็น ในตัวอย่างด้านบน ค่านี้กำหนดเป็น data.ExpiresInSeconds
  • ตัวดึงข้อมูลโทเค็นการตรวจสอบสิทธิ์ต้องส่งเวลาหมดอายุ (เป็นวินาทีนับจากเวลาดึงข้อมูล) ไปยังไลบรารีดังที่แสดงในตัวอย่าง
  • SERVER_TOKEN_URL ขึ้นอยู่กับการใช้งานแบ็กเอนด์ของคุณ นี่คือ URL สำหรับตัวอย่างแบ็กเอนด์ของแอป
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/fleet_reader

โหลดแผนที่จาก HTML

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

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

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

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

ยกตัวอย่างผู้ให้บริการสถานที่จัดส่ง

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

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

เริ่มต้นมุมมองแผนที่

หลังจากโหลดไลบรารีการแชร์เส้นทาง JavaScript แล้ว ให้เริ่มต้นมุมมองแผนที่และเพิ่มลงในหน้า HTML หน้าเว็บของคุณควรมีเอลิเมนต์ <div> ที่เก็บมุมมองแผนที่ ในตัวอย่างต่อไปนี้ องค์ประกอบ <div> มีชื่อว่า map_canvas

เพื่อหลีกเลี่ยงเงื่อนไขการแข่งขัน ให้ตั้งรหัสติดตามสำหรับผู้ให้บริการตำแหน่งในการเรียกกลับที่เรียกหลังจากการเริ่มต้นแผนที่

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // 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 will start 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

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // 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 will start 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);

รหัสติดตาม

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

  1. หากมีงานรับสินค้าที่เปิดอยู่ 1 รายการ งานดังกล่าวจะแสดงขึ้น ระบบจะสร้างข้อผิดพลาดขึ้น หากมีงานรับสินค้าที่เปิดอยู่หลายงาน
  2. หากมีงานนำส่งที่เปิดอยู่ 1 รายการ งานดังกล่าวจะแสดงขึ้น โดยข้อผิดพลาดจะเกิดขึ้นเมื่อมีงานการนำส่งที่เปิดอยู่หลายรายการ
  3. หากมีงานนำส่งแบบปิด ให้ทำดังนี้
    • หากมีงานนำส่งที่ปิดไปแล้วเพียง 1 รายการ งานดังกล่าวจะแสดงขึ้น
    • หากมีงานนำส่งที่ปิดไปแล้วหลายรายการ ระบบจะแสดงงานที่มีเวลาขาออกล่าสุด
    • หากมีงานนำส่งที่ปิดไปแล้วหลายรายการ แต่ไม่มีงานที่มีเวลาผลลัพธ์ ระบบจะแสดงข้อผิดพลาด
  4. หากมีงานรับสินค้าที่ปิดไปแล้ว ให้ทำดังนี้
    • หากมีงานรับสินค้าที่ปิดไปแล้ว 1 รายการ งานดังกล่าวจะแสดงขึ้น
    • หากมีงานรับสินค้าที่ปิดไปแล้วหลายรายการ ระบบจะแสดงงานที่มีเวลาขาออกล่าสุด
    • หากมีงานรับสินค้าที่ปิดไปแล้วหลายรายการ และไม่มีงานที่มีเวลาผลลัพธ์ ระบบจะแสดงข้อผิดพลาด
  5. ไม่เช่นนั้น ระบบจะไม่แสดงงาน

ฟังเหตุการณ์การเปลี่ยนแปลง

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

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

จัดการข้อผิดพลาด

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

หยุดติดตาม

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

ปรับแต่งรูปลักษณ์ของแผนที่ฐาน

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

ใช้การจัดรูปแบบแผนที่ในระบบคลาวด์

การจัดรูปแบบแผนที่ในระบบคลาวด์ช่วยให้คุณสร้างและแก้ไขรูปแบบแผนที่สำหรับแอปใดก็ตามที่ใช้ Google Maps ได้จากคอนโซล Google Cloud โดยไม่ต้องเปลี่ยนแปลงโค้ดใดๆ เลย ระบบจะบันทึกรูปแบบแผนที่เป็นรหัสแผนที่ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ หากต้องการใช้รูปแบบกับแผนที่การติดตามการจัดส่งของ JavaScript ให้ระบุ mapId เมื่อสร้าง JourneySharingMapView คุณจะเปลี่ยนหรือเพิ่มช่อง mapId ไม่ได้หลังจากสร้างอินสแตนซ์ JourneySharingMapView แล้ว ตัวอย่างต่อไปนี้แสดงวิธีเปิดใช้รูปแบบแผนที่ที่สร้างไว้ก่อนหน้านี้ด้วยรหัสแผนที่

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

ใช้การจัดรูปแบบแผนที่ตามโค้ด

อีกวิธีในการปรับแต่งรูปแบบแผนที่คือการตั้งค่า mapOptions เมื่อคุณสร้าง JourneySharingMapView

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

ใช้การปรับแต่งเครื่องหมาย

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

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

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

ไลบรารีการติดตามการจัดส่งมีพารามิเตอร์การปรับแต่งต่อไปนี้ใน FleetEngineShipmentLocationProviderOptions

เปลี่ยนรูปแบบเครื่องหมายโดยใช้ MarkerOptions

ตัวอย่างต่อไปนี้แสดงวิธีกำหนดค่าการจัดรูปแบบของเครื่องหมายยานพาหนะด้วยออบเจ็กต์ MarkerOptions ทำตามรูปแบบนี้เพื่อปรับแต่งการจัดรูปแบบของเครื่องหมายโดยใช้การปรับแต่งเครื่องหมายตามที่แสดงข้างต้น

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

เปลี่ยนการจัดรูปแบบเครื่องหมายโดยใช้ฟังก์ชันการปรับแต่ง

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

เพิ่มการจัดการการคลิกลงในตัวทำเครื่องหมาย

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

ใช้การปรับแต่งเส้นประกอบ

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

คุณระบุชุดของ PolylineOptions ให้นำไปใช้กับออบเจ็กต์ Polyline ที่ตรงกันทั้งหมดเมื่อมีการสร้างหรืออัปเดตได้เช่นเดียวกับการปรับแต่งเครื่องหมาย

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

คุณระบุการปรับแต่งได้โดยใช้พารามิเตอร์ที่มีให้ใน FleetEngineShipmentLocationProviderOptions คุณสามารถตั้งค่ากำหนดสถานะเส้นทางต่างๆ ในการเดินทางของรถ เช่น เดินทางแล้ว กำลังเดินทาง หรือยังไม่ได้เดินทาง โดยมีพารามิเตอร์ดังนี้

เปลี่ยนการจัดรูปแบบของวัตถุ Polyline โดยใช้ PolylineOptions

ตัวอย่างต่อไปนี้แสดงวิธีกำหนดค่าการจัดรูปแบบสำหรับออบเจ็กต์ Polyline ด้วย PolylineOptions ทำตามรูปแบบนี้เพื่อปรับแต่งการจัดรูปแบบของออบเจ็กต์ Polyline โดยใช้การปรับแต่งโพลีไลน์แบบใดก็ได้ที่แสดงก่อนหน้านี้

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

เปลี่ยนการจัดรูปแบบวัตถุ Polyline โดยใช้ฟังก์ชันการปรับแต่ง

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

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

ควบคุมการเปิดเผยของ Polyline ออบเจ็กต์

โดยค่าเริ่มต้น ระบบจะแสดงวัตถุทั้งหมด Polyline รายการ หากต้องการทำให้ออบเจ็กต์ Polyline ไม่ปรากฏ ให้ตั้งค่าพร็อพเพอร์ตี้ visible ของออบเจ็กต์ดังกล่าว ดังนี้

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

แสดง InfoWindow สำหรับยานพาหนะหรือเครื่องหมายระบุตำแหน่ง

คุณสามารถใช้ InfoWindow เพื่อแสดงข้อมูลเพิ่มเติมเกี่ยวกับยานพาหนะหรือเครื่องหมายระบุตำแหน่ง

ตัวอย่างต่อไปนี้แสดงวิธีสร้าง InfoWindow และติดไว้กับเครื่องหมายยานพาหนะ

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

ปิดใช้การปรับให้พอดีอัตโนมัติ

คุณสามารถหยุดแผนที่ไม่ให้ปรับให้พอดีกับวิวพอร์ตกับยานพาหนะและเส้นทางที่คาดไว้โดยอัตโนมัติได้โดยปิดใช้งานการปรับให้พอดีอัตโนมัติ ตัวอย่างต่อไปนี้แสดงวิธีปิดใช้การปรับให้พอดีอัตโนมัติเมื่อกําหนดค่ามุมมองแผนที่การแชร์เส้นทาง

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.   
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

แทนที่แผนที่ที่มีอยู่

คุณสามารถใช้ไลบรารีการติดตามการจัดส่งของ JavaScript เพื่อแทนที่แผนที่ที่มีอยู่ซึ่งมีเครื่องหมายหรือการปรับแต่งอื่นๆ โดยไม่สูญเสียการปรับแต่งเหล่านั้น

ตัวอย่างเช่น สมมติว่าคุณมีหน้าเว็บที่มีเอนทิตี google.maps.Map มาตรฐานซึ่งมีเครื่องหมายแสดงอยู่

<!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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, map: map});
}
    </script>
    <!-- Load the API from the specified URL.
       * The async attribute allows the browser to render the page while the API loads.
       * The key parameter will contain your own API key (which is not needed for this tutorial).
       * 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>

วิธีเพิ่มไลบรารีการแชร์เส้นทาง JavaScript

  1. เพิ่มโค้ดที่ใช้เป็นค่าเริ่มต้นสำหรับโทเค็นการตรวจสอบสิทธิ์
  2. เริ่มต้นผู้ให้บริการตำแหน่งในฟังก์ชัน initMap()
  3. เริ่มต้นมุมมองแผนที่ในฟังก์ชัน initMap() มุมมองนี้มีแผนที่
  4. ย้ายการปรับแต่งของคุณลงในฟังก์ชัน Callback สำหรับการเริ่มต้นมุมมองแผนที่
  5. เพิ่มไลบรารีตำแหน่งลงในตัวโหลด API

ตัวอย่างต่อไปนี้แสดงการเปลี่ยนแปลงที่จะเกิดขึ้น

<!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>
let locationProvider;

// (1) Authentication Token Fetcher
function authTokenFetcher(options) {
  // options is a record containing two keys called 
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
      if (!response.ok) {
        throw new Error(response.statusText);
      }
      const data = await response.json();
      return {
        token: data.Token,
        expiresInSeconds: data.ExpiresInSeconds
      };
}

// Initialize and add the map
function initMap() {
  // (2) Initialize location provider.
  locationProvider = new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
    YOUR_PROVIDER_ID,
    authTokenFetcher,
  });

  // (3) Initialize map view (which contains the map).
  const mapView = new google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map'),
    locationProviders: [locationProvider],
    // any styling options
  });

  locationProvider.trackingId = TRACKING_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, initially centered at Mountain View, CA.
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, now positioned at Uluru
    var marker = new google.maps.Marker({position: uluru, map: map});
  };

    </script>
    <!-- Load the API from the specified URL
      * The async attribute allows the browser to render the page while the API loads
      * The key parameter will contain your own API key (which is not needed for this tutorial)
      * The callback parameter executes the initMap() function
      *
      * (5) Add the journey sharing library to the API loader.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

หากคุณมีแพ็กเกจที่ติดตามซึ่งมีรหัสที่ระบุไว้ใกล้กับ Uluru ตอนนี้ก็จะแสดงผลบนแผนที่ด้วย