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

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

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

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

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

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

التفاصيل الأساسية

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

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

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

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

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

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

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

  • لا يتوفّر رمز مميّز صالح، مثلاً عندما لم تستدعِ حزمة SDK أداة الجلب عند تحميل صفحة جديدة، أو عندما لم تعرض أداة الجلب رمزًا مميّزًا.

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

  • الرمز المميز على وشك انتهاء الصلاحية خلال دقيقة واحدة.

بخلاف ذلك، تستخدم مكتبة Fleet tracking 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,
  };
}

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