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