برای شروع جلسه ناوبری، برنامه شما باید به صورت پویا یک URL راهاندازی برای باز کردن Google Maps یا Waze ایجاد کند. این راهنما نحوه استفاده از توکن سفر تأیید شده از Create a trip را برای راهاندازی Google Maps یا Waze و پیکربندی تجربه بازگشت به برنامه شما شرح میدهد.
نحوهی اجرای نقشههای گوگل یا ویز
برای راهاندازی Google Maps یا Waze، باید راهی فراهم کنید تا رانندگان بتوانند یک جلسه ناوبری را از برنامه شما شروع کنند، URL راهاندازی را با پارامترهای مورد نیاز بسازید و شناسه برنامه خود را برای نسبت دادن جلسه ارائه دهید.
به رانندگان اجازه دهید ناوبری را از برنامه شما شروع کنند
شما باید راهی برای رانندگان فراهم کنید تا بتوانند از طریق اپلیکیشن شما مسیریابی را شروع کنند. اگر به رانندگان اجازه میدهید که با استفاده از یک دکمه، نقشههای گوگل یا ویز را اجرا کنند، از انتساب صحیح اطمینان حاصل کنید و با برچسبگذاری واضح آن، از سردرگمی جلوگیری کنید. به عنوان مثال، متن "نقشههای گوگل" یا "ویز" را روی یا نزدیک دکمه قرار دهید.
ساخت URL راهاندازی
برای شروع یک جلسه ناوبری، یک URL راهاندازی Navigation Connect ایجاد کنید. این URL رشتهای است که شامل مقصد، توکن سفر و پارامترهای ناوبری مورد نیاز است. این URL مشابه URL استاندارد Google Maps یا Waze Deep Link عمل میکند.
برای اجرای نقشههای گوگل یا ویز در دستگاه راننده، از مکانیزم مخصوص هر پلتفرم استفاده کنید:
- اندروید: رشته URL را در یک
Intentارسال کنید. - iOS: از رشته URL به عنوان یک پیوند جهانی (یا پیوند عمیق) استفاده کنید.
فرمت کردن مقصد
برای اطمینان از اینکه گوگل مپس یا ویز میتوانند مسیر را با موفقیت محاسبه کنند، هنگام قالببندی مقصد خود، قوانین زیر را رعایت کنید:
دقیقاً یک مقصد قابل دسترسی را مشخص کنید. میتوانید مقصد را به صورت یک رشته آدرس، مختصات طول/عرض جغرافیایی یا یک شناسه مکان ارسال کنید.
از چندین نقطه مسیر استفاده نکنید. اگر چندین نقطه مسیر را مستقیماً در URL وارد کنید، Google Maps یا Waze خطایی نمایش میدهد. در عوض، سفرهای جداگانه ایجاد کنید.
اضافه کردن توکن سفر و پارامترهای ناوبری
برای تکمیل URL راهاندازی، باید توکن سفر تأیید شدهای را که از « ایجاد درخواست سفر» دریافت کردهاید، وارد کنید. همچنین باید پارامترهای ناوبری که به Google Maps یا Waze میگویند ناوبری فعال را شروع کنند، وارد کنید.
نقشههای گوگل
برای نقشههای گوگل، پارامترهای زیر را در URL راهاندازی خود وارد کنید:
-
dir_action=navigate: این پارامتر ناوبری فعال را اجباری میکند. -
action_token: این پارامتر توکن سفر احراز هویت شده شما را ارائه میدهد.
مثالهای زیر نحوه قالببندی URL راهاندازی برای نقشههای گوگل با استفاده از قالبهای مقصد مختلف را نشان میدهند:
- مختصات طول و عرض جغرافیایی:
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، پارامترهای زیر را در 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
شناسه برنامه خود را وارد کنید (فقط اندروید)
برای نسبت دادن یک جلسه ناوبری به برنامه خود در اندروید، شناسه برنامه تأیید شده خود را ارائه دهید. این شناسه برنامه شما را به عنوان منبع سفر شناسایی میکند تا Google Maps یا Waze بتوانند سفر فعال را به پلتفرم شما پیوند دهند.
ارائه شناسه برنامه شما، ویژگیهای زیر را فعال میکند:
- اشتراکگذاری دادهها را مجاز کنید: تأیید میکند که برنامه شما مجاز به دریافت دادههای سفر فعال است.
- فعال کردن رضایت راننده: صفحه رضایت را با نام کسب و کار و سیاست حفظ حریم خصوصی شما پر میکند و تضمین میکند که راننده میداند چه کسی موقعیت مکانی و زمان تقریبی رسیدن به مقصد خود را دریافت میکند.
- فعال کردن دکمه بازگشت: به Google Maps یا Waze این امکان را میدهد که یک دکمه بازگشت اختصاصی بسازند تا رانندگان بتوانند به برنامه شما برگردند.
برای ارسال شناسه برنامه به Google Maps یا Waze در اندروید، نام بسته خود را با استفاده از Intent.EXTRA_REFERRER_NAME به launch intent (که حاوی رشته URL راهاندازی است) اضافه کنید.
مثال زیر نحوه اضافه کردن نام پکیج به intent را نشان میدهد:
intent.putExtra(Intent.EXTRA_REFERRER_NAME, "android-app://${application.packageName}")
چگونه به رانندگان اجازه دهیم به برنامه شما برگردند
نویگیشن کانکت یک نوار پایین (گوگل مپ) یا یک دکمه بازگشت برند (ویز) را نمایش میدهد تا راننده بتواند در هر نقطهای از سفر یا وقتی به مقصد میرسد، به راحتی به برنامه شما بازگردد.
اندروید
شما باید یک PendingIntent ایجاد کنید که به activity برنامه شما اشاره کند. این PendingIntent به عنوان یک تابع اضافی به launch intent با استفاده از کلید دقیق "pendingIntent" اضافه کنید. وقتی کاربر دکمه return را لمس میکند، Google Maps یا Waze این intent را اجرا میکنند تا برنامه شما را به پیشزمینه بیاورد.
intent.putExtra("pendingIntent", getPendingIntent())iOS (فقط Waze)
برای فعال کردن دکمه بازگشت، نیازی به اضافه کردن چیزی به آدرس اینترنتی (URL) هنگام شروع برنامه ندارید. ویز (Waze) به طور خودکار از لینک جهانی (Universal Link) که هنگام تأیید برنامه ثبت کردهاید، استفاده میکند.
نمونههای کد
نمونههای کد زیر نحوهی اجرای نقشههای گوگل یا ویز را از برنامهی شما با استفاده از Navigation Connect و فعال کردن دکمهی «بازگشت به برنامه» نشان میدهند.
نقشههای گوگل (اندروید)
کد کاتلین زیر یک تابع نمونه را نشان میدهد که یک جلسه 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())
}ویز (اندروید)
کد کاتلین زیر یک تابع نمونه را نشان میدهد که یک جلسه 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())
}ویز (آیاواس)
کد 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)
}
}