باستخدام حزمة تطوير البرامج (SDK) للمستهلكين في JavaScript، يمكن لتطبيق المستهلك عرض الموقع الجغرافي للمركبات والمواقع الجغرافية الأخرى المهمة التي يتم تتبّعها في Fleet Engine على خريطة مستندة إلى الويب. يتيح ذلك للمستخدمين من المستهلكين الاطّلاع على حالة شحناتهم. يفترض هذا الدليل أنّك قد أعددت Fleet Engine مع مشروع Google Cloud ومفاتيح واجهة برمجة التطبيقات المرتبطة به. راجِع Fleet Engine للحصول على التفاصيل.
يمكنك إعداد حزمة JavaScript Consumer SDK باتّباع الخطوات التالية:
تفعيل 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 لتطبيقك المستند إلى الويب من أجل الوصول إلى Fleet Engine. يرسل تطبيقك المستند إلى الويب رموز JWT هذه مع طلباته لكي يتعرّف Fleet Engine على الطلبات على أنّها موثّقة ومصرّح لها بالوصول إلى البيانات في الطلب. للحصول على تعليمات حول تنفيذ JWT من جهة الخادم، اطّلِع على إصدار رموز الويب المميزة بتنسيق JSON ضمن أساسيات Fleet Engine.
على وجه التحديد، يُرجى مراعاة ما يلي عند استخدام حزمة تطوير البرامج JavaScript Consumer SDK لتتبُّع الشحنات:- إرشادات عامة لإصدار رموز 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
مثال - إنشاء أداة جلب لرمز المصادقة المميز
توضّح الأمثلة التالية كيفية إنشاء أداة لجلب رموز الدخول:
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,
};
}