باستخدام حزمة تطوير البرامج (SDK) للمستهلكين في JavaScript، يمكن لتطبيق المستهلك عرض الموقع الجغرافي للمركبات والمواقع الجغرافية الأخرى التي يتم تتبُّعها في Fleet Engine على خريطة مستندة إلى الويب. يتيح ذلك للمستهلكين الاطّلاع على مستوى تقدّم رحلة السائق. يفترض هذا الدليل أنّك أعددت Fleet Engine مع مشروع Google Cloud ومفاتيح واجهة برمجة التطبيقات المرتبطة به. لمزيد من التفاصيل، يُرجى الاطّلاع على Fleet Engine.
يمكنك إعداد حزمة تطوير البرامج (SDK) للمستهلك في JavaScript باتّباع الخطوات التالية:
تفعيل Maps JavaScript API
فعِّل Maps JavaScript API في Google Cloud Console. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة تفعيل واجهات برمجة التطبيقات في مستندات Google Cloud. يؤدي ذلك إلى تفعيل "حزمة تطوير البرامج (SDK) للمستهلك" في JavaScript.
إعداد التفويض
يتطلّب Fleet Engine استخدام رموز JSON المميّزة للويب (JWT) لطلبات إجراءات واجهة برمجة التطبيقات من البيئات المنخفضة الثقة: الهواتف الذكية والمتصفّحات.
ينشأ رمز JWT على الخادم الخاص بك، ويتم توقيعه وتشفيره وتمريره إلى العميل للتفاعلات اللاحقة مع الخادم إلى أن تنتهي صلاحيته أو يصبح غير صالح.
التفاصيل الأساسية
- استخدِم بيانات الاعتماد التلقائية للتطبيق للمصادقة على Fleet Engine ومنحه الإذن.
- استخدِم حساب خدمة مناسبًا لتوقيع رموز JWT. يمكنك الاطّلاع على أدوار حساب خدمة Fleet Engine في أساسيات Fleet Engine.
كيف تعمل عملية التفويض؟
تتضمّن عملية التفويض باستخدام بيانات Fleet Engine كلاً من التنفيذ من جهة الخادم ومن جهة العميل.
التفويض من جهة الخادم
قبل إعداد المصادقة والتفويض في تطبيقك المستنِد إلى الويب، يجب أن يتمكّن خادم الخلفية من إصدار رموز JSON Web Tokens لتطبيقك المستنِد إلى الويب من أجل الوصول إلى Fleet Engine. يرسل تطبيقك المستند إلى الويب رموز JWT هذه مع طلباته ليتعرّف Fleet Engine على الطلبات على أنّها مصادَق عليها ومصرَّح لها بالوصول إلى البيانات في الطلب. للحصول على تعليمات حول تنفيذ رمز الويب المميّز JSON من جهة الخادم، يُرجى الاطّلاع على إصدار رموز الويب المميّزة JSON ضمن أساسيات Fleet Engine.
على وجه التحديد، يُرجى مراعاة ما يلي في ما يتعلّق بحزمة JavaScript Consumer SDK لمشاركة تقدّم الرحلة:- إرشادات عامة لإصدار رموز الويب المميّزة بتنسيق JSON
- إرشادات حول رمز JWT لرحلات النقل عند الطلب
- مثال على رمز مميّز لعملية مستهلك
التفويض من جهة العميل
عند استخدام حزمة JavaScript Consumer SDK، تطلب هذه الحزمة رمزًا مميزًا من الخادم باستخدام أداة جلب رمز التفويض. ويحدث ذلك في أيّ من الحالات التالية:
لا يتوفّر رمز مميّز صالح، مثلاً عندما لا تطلب حزمة تطوير البرامج (SDK) من أداة الجلب تحميل صفحة جديدة، أو عندما لا تعرض أداة الجلب رمزًا مميّزًا.
انتهت صلاحية الرمز المميّز.
تنتهي صلاحية الرمز المميّز خلال دقيقة واحدة.
وإلا، ستستخدم حزمة SDK للمستهلكين المستندة إلى JavaScript الرمز المميّز الصالح الذي تم إصداره سابقًا ولن تستدعي أداة الجلب.
إنشاء أداة جلب الرموز المميّزة للتفويض
أنشئ أداة جلب الرمز المميّز للتفويض باستخدام الإرشادات التالية:
يجب أن يعرض الجالب بنية بيانات تتضمّن حقلَين، يتم تضمينهما في
Promiseعلى النحو التالي:سلسلة
token.رقم
expiresInSecondsتنتهي صلاحية الرمز المميّز بعد هذه المدة من جلبه. يجب أن يمرّر برنامج جلب الرموز المميّزة للمصادقة وقت انتهاء الصلاحية بالثواني، من وقت الجلب إلى المكتبة كما هو موضّح في المثال.
يجب أن يطلب برنامج الجلب عنوان URL على خادمك لاسترداد رمز مميّز. يعتمد عنوان URL هذا، وهو
SERVER_TOKEN_URL، على عملية التنفيذ في الخلفية. عنوان URL في المثال التالي مخصّص للواجهة الخلفية لنموذج التطبيق على GitHub:https://SERVER_URL/token/consumer/TRIPID
مثال: إنشاء أداة جلب رمز المصادقة المميّز
توضّح الأمثلة التالية كيفية إنشاء أداة جلب رمز التفويض:
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,
};
}