باستخدام حزمة JavaScript Consumer SDK، يمكن لتطبيق المستهلك عرض الموقع الجغرافي للمركبات والمواقع الجغرافية الأخرى محل الاهتمام التي يتم تتبُّعها في 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 على الطلبات على أنّها مصادَق عليها ومصرَّح لها بالوصول إلى البيانات في الطلب. للحصول على تعليمات حول تنفيذ JWT من جهة الخادم، يُرجى الاطّلاع على إصدار رموز 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,
};
}