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

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

يمكنك إعداد حزمة JavaScript Consumer SDK باتّباع الخطوات التالية:

1. فعِّل Maps JavaScript API.
2. إعداد التفويض

تفعيل Maps JavaScript API

فعِّل Maps JavaScript API في مشروع Google Cloud Console الذي تستخدمه لمثيل Fleet Engine. لمزيد من التفاصيل، يُرجى الاطّلاع على تفعيل واجهات برمجة التطبيقات في مستندات Maps JavaScript API.

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

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

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

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

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

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

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

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

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

• الإرشادات العامة لإصدار رموز JSON المميّزة للويب
• إرشادات بشأن رموز JWT للمهام المُجدوَلة
• مثال على رمز مميز لتطبيق موجّه للمستهلكين

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

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

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

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

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

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

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

أنشئ أداة جلب رمز التفويض باستخدام الإرشادات التالية:

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

  • سلسلة token

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

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

  • https://SERVER_URL/token/delivery_consumer/TRACKING_ID

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

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

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

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

• متابعة شحنة