لبدء جلسة التنقّل، يجب أن ينشئ تطبيقك عنوان URL للإطلاق بشكل ديناميكي لفتح "خرائط Google" أو Waze. يوضّح هذا الدليل كيفية استخدام الرمز المميّز للرحلة الذي تمت مصادقته من إنشاء رحلة لتشغيل "خرائط Google" أو Waze وضبط تجربة العودة إلى تطبيقك.
كيفية تشغيل "خرائط Google" أو Waze
لتشغيل "خرائط Google" أو Waze، عليك توفير طريقة تتيح للسائقين بدء جلسة تنقّل من تطبيقك، وإنشاء عنوان URL للتشغيل باستخدام المَعلمات المطلوبة، وتقديم رقم تعريف تطبيقك لتحديد مصدر الجلسة.
السماح للسائقين ببدء التنقّل من تطبيقك
يجب توفير طريقة للسائقين لبدء التنقّل من تطبيقك. إذا كنت تسمح للسائقين بتشغيل "خرائط Google" أو Waze باستخدام زر، تأكَّد من توفير الإسناد المناسب وتجنُّب الالتباس من خلال تصنيفه بوضوح. على سبيل المثال، يمكنك وضع النص "خرائط Google" أو "Waze" على الزر أو بالقرب منه.
إنشاء عنوان URL للإطلاق
لبدء جلسة تنقّل، أنشئ عنوان URL لتشغيل Navigation Connect. عنوان URL هذا عبارة عن سلسلة تحتوي على الوجهة والرمز المميّز للرحلة ومَعلمات التنقّل المطلوبة. وتعمل هذه الروابط بشكل مشابه لعناوين URL العادية في "خرائط Google" أو رابط عميق في Waze.
لتشغيل "خرائط Google" أو Waze على جهاز السائق، استخدِم الآلية الخاصة بالنظام الأساسي:
- Android: مرِّر سلسلة عنوان URL في
Intent. - نظام التشغيل iOS: استخدِم سلسلة عنوان URL كرابط عام (أو رابط لصفحة معيّنة في التطبيق).
تنسيق الوجهة
لضمان قدرة "خرائط Google" أو Waze على حساب المسار بنجاح، يجب الالتزام بالقواعد التالية عند تنسيق وجهتك:
حدِّد وجهة واحدة يمكن الوصول إليها. يمكنك تمرير الوجهة كسلسلة عنوان أو إحداثيات خطوط العرض/الطول أو رقم تعريف مكان.
لا تستخدِم نقاطًا متعددة على المسار. إذا مرّرت عدة نقاط على المسار مباشرةً في عنوان URL، سيعرض تطبيق "خرائط Google" أو Waze خطأً. بدلاً من ذلك، أنشئ رحلات منفصلة.
إضافة رمز الرحلة المميّز ومَعلمات التنقّل
لإكمال عنوان URL الخاص بالإطلاق، يجب تضمين الرمز المميّز للرحلة الذي تمت مصادقته والذي تلقّيته من طلب إنشاء رحلة. يجب أيضًا تضمين مَعلمات التنقّل التي تطلب من "خرائط Google" أو Waze بدء التنقّل النشط.
خرائط Google
بالنسبة إلى "خرائط Google"، يجب تضمين المَعلمات التالية في عنوان URL الخاص بالإطلاق:
dir_action=navigate: تفرض هذه المَعلمة التنقّل النشط.action_token: توفّر هذه المَعلمة الرمز المميّز للرحلة الذي تمت مصادقته.
توضّح الأمثلة التالية كيفية تنسيق عنوان URL لتشغيل "خرائط Google" باستخدام تنسيقات مختلفة للوجهة:
-
إحداثيات خطوط العرض/الطول:
https://www.google.com/maps/dir/?api=1&destination=-33.8569%2C151.2152&dir_action=navigate&action_token=TRIP_TOKEN
-
سلسلة العنوان:
https://www.google.com/maps/dir/?api=1&destination=1600%20Amphitheatre%20Parkway...&dir_action=navigate&action_token=TRIP_TOKEN
-
رقم تعريف المكان:
https://www.google.com/maps/dir/?api=1&destination_place_id=PLACE_ID&dir_action=navigate&action_token=TRIP_TOKEN
Waze
بالنسبة إلى Waze، يجب تضمين المَعلمات التالية في عنوان URL الخاص بالتشغيل:
navigate=yes: تفرض هذه المَعلمة التنقّل النشط.external_trip_token: توفّر هذه المَعلمة الرمز المميّز للرحلة الذي تمت مصادقته.
توضّح الأمثلة التالية كيفية تنسيق عنوان URL الخاص بتشغيل Waze باستخدام تنسيقات مختلفة للوجهة:
-
إحداثيات خطوط العرض/الطول:
https://waze.com/ul?ll=-33.8569%2C151.2152&navigate=yes&external_trip_token=TRIP_TOKEN
-
سلسلة العنوان:
https://waze.com/ul?&q=1600%20Amphitheatre...&navigate=yes&external_trip_token=TRIP_TOKEN
-
رقم تعريف المكان:
https://waze.com/ul?google_place_id=PLACE_ID&navigate=yes&external_trip_token=TRIP_TOKEN
تقديم معرّف التطبيق (على أجهزة Android فقط)
لبدء رحلة باستخدام Navigation Connect، يجب تحديد جلسة تنقّل لتطبيقك على Android. لإجراء ذلك، قدِّم رقم تعريف التطبيق الذي تم التحقّق منه. يحدّد هذا المعرّف تطبيقك كمصدر للرحلة، ما يتيح لـ "خرائط Google" أو Waze ربط الرحلة النشطة بمنصتك. يؤدي عدم توفّر رقم تعريف التطبيق أو عدم صلاحيته إلى تعذُّر مصادقة رمز الرحلة المميّز.
يؤدي تقديم رقم تعريف التطبيق إلى تفعيل الميزات التالية:
- تفويض مشاركة البيانات: يتحقّق هذا الإجراء من أنّ تطبيقك مصرَّح له بتلقّي بيانات الرحلات النشطة.
- تفعيل موافقة السائق: تملأ شاشة طلب الموافقة باسم مؤسستك وسياسة الخصوصية، ما يضمن معرفة السائق بالجهة التي تتلقّى موقعه الجغرافي في الوقت الفعلي والوقت المقدَّر للوصول.
- تفعيل زر الرجوع: يتيح هذا الإعداد لـ "خرائط Google" أو Waze إنشاء زر رجوع يحمل علامة تجارية لكي يتمكّن السائقون من العودة إلى تطبيقك.
لتمرير معرّف التطبيق إلى "خرائط Google" أو Waze على Android، أضِف اسم الحزمة إلى
الهدف من الإطلاق (الذي يحمل سلسلة عنوان URL للإطلاق) باستخدام
Intent.EXTRA_REFERRER_NAME.
يوضّح المثال التالي كيفية إضافة اسم الحزمة إلى الغرض:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
كيفية السماح للسائقين بالعودة إلى تطبيقك
تعرض ميزة Navigation Connect شريطًا سفليًا ("خرائط Google") أو زر رجوع يحمل علامة تجارية (Waze) ليتمكّن السائق من التبديل السلس إلى تطبيقك في أي وقت أثناء الرحلة أو عند الوصول إلى الوجهة.
Android
يجب إنشاء PendingIntent يشير إلى نشاط تطبيقك. أرفِق هذا الـ PendingIntent كإضافة إلى نية الإطلاق
باستخدام المفتاح "pendingIntent" بالضبط. عندما ينقر المستخدم على زر الرجوع، ينفّذ تطبيق "خرائط Google" أو Waze هذا الغرض لإظهار تطبيقك في المقدّمة.
intent.putExtra("pendingIntent", getPendingIntent())iOS (تطبيق Waze فقط)
لست بحاجة إلى إضافة أي شيء إلى عنوان URL الخاص بالإطلاق لتفعيل زر الرجوع. يستخدم تطبيق Waze تلقائيًا الرابط العام الذي سجّلته عند إثبات ملكية تطبيقك.
عيّنات تعليمات برمجية
توضّح عيّنات الرموز البرمجية التالية كيفية تشغيل "خرائط Google" أو Waze من تطبيقك باستخدام Navigation Connect وتفعيل زر "العودة إلى التطبيق".
"خرائط Google" (على أجهزة Android)
يعرض رمز Kotlin التالي نموذج دالة تبدأ جلسة Navigation Connect مع المَعلمات المطلوبة.
private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"
private fun launchNavConnect() {
val jwtToken = "TRIP_TOKEN"
try {
// URL Encode the destination
val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
val navConnectUrl = "https://www.google.com/maps/dir/?api=1" +
"&destination=$encodedDestination" +
"&dir_action=navigate" +
"&action_token=$jwtToken"
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
// Explicitly set GMM package to ensure it opens in Google Maps
intent.setPackage("com.google.android.apps.maps")
// Add your application ID to the intent
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
// set up the NavConnect back button
intent.putExtra("pendingIntent", getPendingIntent())
startActivity(intent)
} catch (e: Exception) {
// handle errors
}
}
private fun getPendingIntent(): PendingIntent? {
val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
val flags = PendingIntent.FLAG_IMMUTABLE
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
return PendingIntent.getActivity(application, 0, returnIntent, flags)
}
val options =
ActivityOptions.makeBasic()
.setPendingIntentCreatorBackgroundActivityStartMode(
ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
)
return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
}Waze (Android)
يعرض رمز Kotlin التالي نموذج دالة تبدأ جلسة Navigation Connect مع المَعلمات المطلوبة.
private val destinationAddress = "1600 Amphitheatre Parkway, Mountain View, CA 94043"
private fun launchNavConnect() {
val tripToken = "TRIP_TOKEN"
try {
// URL Encode the destination
val encodedDestination = URLEncoder.encode(destinationAddress, "UTF-8")
val navConnectUrl = "https://waze.com/ul?" +
"&q=$encodedDestination" +
"&navigate=yes" +
"&external_trip_token=$tripToken"
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(navConnectUrl))
// Explicitly set package name to ensure it opens in Waze
intent.setPackage("com.waze")
// Add your application ID to the intent
val referrerName = "android-app://${application.packageName}"
intent.putExtra(Intent.EXTRA_REFERRER_NAME, referrerName)
// set up the NavConnect back button
intent.putExtra("pendingIntent", getPendingIntent())
startActivity(intent)
} catch (e: Exception) {
// handle errors
}
}
private fun getPendingIntent(): PendingIntent? {
val returnIntent = Intent(application, MainActivity::class.java) // replace with your activity to launch
returnIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
val flags = PendingIntent.FLAG_IMMUTABLE
if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
return PendingIntent.getActivity(application, 0, returnIntent, flags)
}
val options =
ActivityOptions.makeBasic()
.setPendingIntentCreatorBackgroundActivityStartMode(
ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
)
return PendingIntent.getActivity(application, 0, returnIntent, flags, options.toBundle())
}Waze (iOS)
يعرض رمز Swift التالي نموذج دالة تبدأ جلسة Navigation Connect مع المَعلمات المطلوبة.
openWazeUrl(queryItems: [URLQueryItem(name: "q", value: "1600 Amphitheatre Parkway")])
private func openWazeUrl(queryItems: [URLQueryItem]) {
var components = URLComponents()
components.scheme = "https"
components.host = "waze.com"
components.path = "/ul"
// Create a mutable copy of the queryItems.
var mutableQueryItems = queryItems
// Add Trip Token
guard let tokenText = tokenField.text, !tokenText.isEmpty else {
return
}
let token = URLQueryItem(name: "external_trip_token", value: tokenText)
mutableQueryItems.append(token)
// Add compulsory params
mutableQueryItems.append(URLQueryItem(name: "navigate", value: "yes"))
// Construct and Launch URL
components.queryItems = mutableQueryItems
guard let url = components.url else {
return
}
UIApplication.shared.open(url, options: [:], completionHandler: nil)
}
}