إعداد مكتبة تتبُّع مجموعة JavaScript

قبل استخدام مكتبة تتبُّع الأسطول باستخدام JavaScript، تأكَّد من أنّك على دراية بخدمة Fleet Engine وأعدّتها. لمعرفة التفاصيل، يُرجى الاطّلاع على Fleet Engine.

يوضّح هذا المستند كيفية تفعيل التفويض بين تطبيق صفحة الويب وFleet Engine. بعد إعداد طلباتك إلى Fleet Engine باستخدام الرموز المميّزة الصحيحة لمصادقة المستخدمين، ستتمكّن من تتبُّع مركبة على الخريطة.

إعداد التفويض

تتطلّب أداة Fleet Engine استخدام رموز JSON المميّزة للويب (JWT) لطلبات واجهة برمجة التطبيقات من البيئات ذات مستوى الثقة المنخفض: الهواتف الذكية والمتصفّحات.

يبدأ JWT على خادمك، ويتم توقيعه وتشفيره وتمريره إلى العميل لتفاعلات الخادم اللاحقة إلى أن تنتهي صلاحيته أو لم يعُد صالحًا.

التفاصيل الرئيسية

كيف تعمل عملية التفويض؟

يشمل التفويض باستخدام بيانات Fleet Engine تنفيذًا من جهة العميل والخادم معًا.

التفويض من جهة الخادم

قبل إعداد المصادقة والتفويض في تطبيق تتبُّع مركبات الأسطول، يجب أن يكون خادم الخلفية قادرًا على إصدار رموز الويب المميّزة بتنسيق JSON إلى تطبيق تتبُّع مركبات الأسطول للوصول إلى Fleet Engine. يُرسِل تطبيق تتبُّع أسطولك مع طلباتك هذه الرموز المجزّأة لبروتوكول أمان طبقة النقل (JWT) حتى يتعرّف محرّك الأسطول على الطلبات على أنّها موثَّقة ومفوَّضة بالوصول إلى البيانات الواردة في الطلب. للحصول على تعليمات حول تنفيذ JWT من جهة الخادم، يُرجى الاطّلاع على مقالة إصدار رموًز الويب المميّزة JSON ضمن أساسيات Fleet Engine.

لإنشاء الرموز المميّزة من خادمك عند تنفيذ ميزة تتبُّع الأسطول، اطّلِع على الخطوات التالية:

التفويض من جهة العميل

عند استخدام مكتبة تتبُّع الأسطول في JavaScript، تطلب المكتبة رمز مميّزًا من الخادم باستخدام أداة جلب رمز مميّز التفويض. ويحدث ذلك عندما يكون أيّ مما يلي صحيحًا:

  • لا يتوفّر رمز مميّز صالح، مثلما يحدث عندما لا تستدعي حزمة تطوير البرامج (SDK) أداة الجلب عند loadingتحميل الصفحة مجددًا، أو عندما لا تُرجع أداة الجلب رمزًا مميّزًا.

  • انتهت صلاحية الرمز المميّز.

  • ستنتهي صلاحية الرمز المميّز خلال دقيقة واحدة.

بخلاف ذلك، تستخدم مكتبة تتبُّع الأسطول في JavaScript الرمز المميّز الصالح الذي تم إصداره سابقًا ولا تستدعي أداة الجلب.

إنشاء أداة جلب رمز مميّز لمنح الأذونات

أنشئ أداة جلب الرمز المميّز للاعتماد باستخدام الإرشادات التالية:

  • يجب أن يعرض أداة الجلب بنية بيانات تتضمّن حقلَين، يتم لفّهما في علامة Promise على النحو التالي:

    • سلسلة token

    • رقم expiresInSeconds تنتهي صلاحية الرمز المميَّز بعد هذه المدة بعد استرجاعه. يجب أن يقدّم أداة جلب رمز المصادقة وقت انتهاء صلاحية بالثواني، بدءًا من وقت الجلب إلى المكتبة كما هو موضّح في المثال.

  • يجب أن يطلب أداة الجلب عنوان URL على خادمك لاسترداد رمز مميّز. يعتمد عنوان URL هذا، أي SERVER_TOKEN_URL، على عملية التنفيذ في الخلفية. المثال التالي على عنوان URL مخصّص لنموذج الخلفية للتطبيق على GitHub:

    • https://SERVER_URL/token/fleet_reader

مثال: إنشاء أداة جلب رمز مميّز للتفويض

توضِّح الأمثلة التالية كيفية إنشاء أداة جلب رمز مميّز للتفويض:

JavaScript

async 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.ExpiresInSeconds,
  };
}

الخطوات التالية