إعداد "حزمة تطوير البرامج (SDK) للمستهلكين" بلغة JavaScript

باستخدام حزمة تطوير البرامج (SDK) الخاصة بمستهلك JavaScript، يمكن لتطبيق المستهلك عرض مواقع المركبات والمواقع الأخرى ذات الأهمية التي يتم تتبُّعها في Fleet Engine على خريطة مستندة إلى الويب. يتيح ذلك للمستهلكين الاطّلاع على مستوى تقدّم رحلة السائق. يفترض هذا الدليل أنّك أعددت Fleet Engine باستخدام مشروع Google Cloud ومفاتيح واجهة برمجة التطبيقات المرتبطة به. راجِع Fleet Engine للاطّلاع على التفاصيل.

يمكنك إعداد حزمة تطوير البرامج (SDK) لإصدار JavaScript المخصّص للمستهلكين باتّباع الخطوات التالية:

1. تفعيل واجهة برمجة تطبيقات JavaScript للخرائط
2. إعداد التفويض

تفعيل Maps JavaScript API

تفعيل واجهة برمجة تطبيقات JavaScript للخرائط في Google Cloud Console لمزيد من التفاصيل، يُرجى الاطّلاع على تفعيل واجهات برمجة التطبيقات في مستندات Google Cloud. يؤدي ذلك إلى تفعيل حزمة تطوير البرامج (SDK) للمستهلك لبرنامج JavaScript.

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

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

يجب أن تتم مصادقة الخلفية وتفويضها ضد Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيق العادية. احرص على استخدام ملفّات JWT التي تم توقيعها من خلال حساب خدمة مناسب. للاطّلاع على قائمة بأدوار حسابات الخدمة، اطّلِع على أدوار حساب خدمة Fleet Engine في أساسيات Fleet Engine.

في المقابل، يجب أن تتم المصادقة والتفويض في الخلفية باستخدام بيانات الاعتماد التلقائية للتطبيق العادية وآليات Fleet Engine.

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

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

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

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

• الإرشادات العامة لإصدار الرموز المميّزة للويب JSON
• إرشادات حول ملفات JWT للرحلات عند الطلب
• مثال على رمز مميّز لعملية مستهلك

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

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

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

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

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

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

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

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

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

  • سلسلة token.

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

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

  • https://SERVER_URL/token/consumer/TRIPID

مثال: إنشاء أداة جلب رمز مميّز للمصادقة

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

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

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

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

متابعة رحلة في JavaScript