یک برنامه ناوبری بسازید

این صفحه جزئیات ویژگی‌های مختلف کتابخانه اپلیکیشن خودرو را که می‌توانید برای پیاده‌سازی عملکرد اپلیکیشن ناوبری گام به گام خود استفاده کنید، شرح می‌دهد.

پشتیبانی از ناوبری را در مانیفست خود اعلام کنید

برنامه ناوبری شما باید دسته برنامه خودرو androidx.car.app.category.NAVIGATION را در فیلتر intent از CarAppService خود تعریف کند:

<application>
    ...
   <service
       ...
        android:name=".MyNavigationCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION"/>
      </intent-filter>
    </service>
    ...
</application>

پشتیبانی از اهداف ناوبری

انواع فرمت‌های هدف، برنامه‌های ناوبری را قادر می‌سازد تا با برنامه‌های دیگر، مانند برنامه‌های نقطه مورد نظر و دستیارهای صوتی، کار کنند.

برای پشتیبانی از این فرمت‌های intent، ابتدا با اضافه کردن فیلترهای intent در مانیفست برنامه خود، پشتیبانی را اعلام کنید. مکان این فیلترهای intent به پلتفرم بستگی دارد:

  • Android Auto : درون عنصر <activity> manifest برای Activity که برای مدیریت intent در زمانی که کاربر از Android Auto استفاده نمی‌کند، استفاده می‌شود.
  • سیستم عامل اندروید خودرو : درون عنصر مانیفست <activity> برای CarAppActivity .

سپس، intent ها را در هر دو فراخوانی onCreateScreen() و onNewIntent() در پیاده سازی Session برنامه خود بخوانید و مدیریت کنید.

قالب‌های مورد نیاز برای اینتنت

برای برآورده کردن الزامات کیفیت NF-6 ، برنامه شما باید اهداف ناوبری را مدیریت کند.

قالب‌های اختیاری برای اینتنت

شما همچنین می‌توانید از قالب‌های intent زیر برای افزایش بیشتر قابلیت همکاری برنامه خود پشتیبانی کنید:

دسترسی به الگوهای ناوبری

برنامه‌های ناوبری می‌توانند به الگوهای زیر دسترسی داشته باشند که سطحی را در پس‌زمینه به همراه نقشه نمایش می‌دهند و در حین ناوبری فعال، مسیرهای گام به گام را نیز نمایش می‌دهند.

  • NavigationTemplate : الگویی که یک پیام اطلاعاتی اختیاری و تخمین سفر را در حین ناوبری فعال نمایش می‌دهد.
  • MapWithContentTemplate : الگویی که به یک برنامه اجازه می‌دهد تا کاشی‌های نقشه را با نوعی محتوا (مثلاً یک لیست) رندر کند. محتوا معمولاً به صورت یک پوشش روی کاشی‌های نقشه رندر می‌شود، به طوری که نقشه قابل مشاهده است و مناطق پایدار با محتوا تنظیم می‌شوند.

برای جزئیات بیشتر در مورد نحوه طراحی رابط کاربری برنامه ناوبری خود با استفاده از این الگوها، به برنامه‌های ناوبری مراجعه کنید.

برای دسترسی به الگوهای ناوبری، برنامه شما باید مجوز androidx.car.app.NAVIGATION_TEMPLATES را در فایل AndroidManifest.xml خود اعلام کند:

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES"/>
  ...
</manifest>

برای ترسیم نقشه‌ها، مجوز اضافی لازم است.

مهاجرت به MapWithContentTemplate

با شروع از API سطح ۷ اپلیکیشن خودرو، MapTemplate ، PlaceListNavigationTemplate و RoutePreviewNavigationTemplate منسوخ شده‌اند. قالب‌های منسوخ‌شده همچنان پشتیبانی خواهند شد، اما مهاجرت به MapWithContentTemplate اکیداً توصیه می‌شود.

قابلیت‌های ارائه شده توسط این قالب‌ها را می‌توان با استفاده از MapWithContentTemplate پیاده‌سازی کرد. برای مثال به قطعه کدهای زیر مراجعه کنید:

الگوی نقشه 

// MapTemplate (deprecated)
val templateDeprecated = MapTemplate.Builder()
    .setPane(paneBuilder.build())
    .setActionStrip(actionStrip)
    .setHeader(header)
    .setMapController(mapController)
    .build()

// MapWithContentTemplate
val template = MapWithContentTemplate.Builder()
    .setContentTemplate(
        PaneTemplate.Builder(paneBuilder.build())
            .setHeader(header)
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapController(mapController)
    .build()

الگوی ناوبری فهرست مکان 

// PlaceListNavigationTemplate (deprecated)
val templateDeprecated = PlaceListNavigationTemplate.Builder()
    .setItemList(itemListBuilder.build())
    .setHeader(header)
    .setActionStrip(actionStrip)
    .setMapActionStrip(mapActionStrip)
    .build()

// MapWithContentTemplate
val template = MapWithContentTemplate.Builder()
    .setContentTemplate(
        ListTemplate.Builder()
            .setSingleList(itemListBuilder.build())
            .setHeader(header)
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapController(
        MapController.Builder()
            .setMapActionStrip(mapActionStrip)
            .build()
    )
    .build()

RoutePreviewNavigationTemplate 

// RoutePreviewNavigationTemplate (deprecated)
val templateDeprecated = RoutePreviewNavigationTemplate.Builder()
    .setItemList(
        ItemList.Builder()
            .addItem(
                Row.Builder()
                    .setTitle(title)
                    .build()
            )
            .build()
    )
    .setHeader(header)
    .setNavigateAction(
        Action.Builder()
            .setTitle(actionTitle)
            .setOnClickListener { /* onClick */ }
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapActionStrip(mapActionStrip)
    .build()

// MapWithContentTemplate
val template = MapWithContentTemplate.Builder()
    .setContentTemplate(
        ListTemplate.Builder()
            .setSingleList(
                ItemList.Builder()
                    .addItem(
                        Row.Builder()
                            .setTitle(title)
                            .addAction(
                                Action.Builder()
                                    .setTitle(actionTitle)
                                    .setOnClickListener { /* onClick */ }
                                    .build()
                            )
                            .build()
                    )
                    .build()
            )
            .setHeader(header)
            .build()
    )
    .setActionStrip(actionStrip)
    .setMapController(
        MapController.Builder()
            .setMapActionStrip(mapActionStrip)
            .build()
    )
    .build()

برنامه‌های ناوبری باید فراداده‌های ناوبری اضافی را با میزبان (host) تبادل کنند. میزبان از این اطلاعات برای ارائه اطلاعات به واحد اصلی خودرو و جلوگیری از تداخل برنامه‌های ناوبری بر سر منابع مشترک استفاده می‌کند.

فراداده‌های ناوبری از طریق سرویس خودرو NavigationManager که از CarContext قابل دسترسی است، ارائه می‌شوند: 

val navigationManager = carContext.getCarService(NavigationManager::class.java)

شروع، پایان و توقف ناوبری

برای اینکه میزبان بتواند چندین برنامه ناوبری، اعلان‌های مسیریابی و داده‌های خوشه‌ای خودرو را مدیریت کند، باید از وضعیت فعلی ناوبری آگاه باشد. وقتی کاربری ناوبری را شروع می‌کند، NavigationManager.navigationStarted را فراخوانی کنید. به طور مشابه، وقتی ناوبری پایان می‌یابد - مثلاً وقتی کاربر به مقصد خود می‌رسد یا ناوبری را لغو می‌کند - NavigationManager.navigationEnded را فراخوانی کنید.

فقط زمانی که کاربر پیمایش را تمام کرد، NavigationManager.navigationEnded را فراخوانی کنید. برای مثال، اگر نیاز دارید مسیر را در وسط یک سفر دوباره محاسبه کنید، به جای آن از Trip.Builder.setLoading(true) استفاده کنید.

گاهی اوقات، میزبان برای متوقف کردن ناوبری به یک برنامه نیاز دارد و در شیء NavigationManagerCallback که توسط برنامه شما از طریق NavigationManager.setNavigationManagerCallback ارائه می‌شود، تابع onStopNavigation را فراخوانی می‌کند. سپس برنامه باید صدور اطلاعات نوبت بعدی در صفحه نمایش خوشه‌ای، اعلان‌های ناوبری و راهنمای صوتی را متوقف کند.

به‌روزرسانی اطلاعات سفر

در حین ناوبری فعال، NavigationManager.updateTrip را فراخوانی کنید. اطلاعات ارائه شده در این فراخوانی می‌تواند توسط خوشه خودرو و نمایشگرهای سربالا استفاده شود. بسته به وسیله نقلیه خاص مورد استفاده، تمام اطلاعات به کاربر نمایش داده نمی‌شود. به عنوان مثال، واحد سر دسکتاپ (DHU) Step اضافه شده به Trip را نشان می‌دهد، اما اطلاعات Destination را نشان نمی‌دهد.

ترسیم به سمت نمایش خوشه‌ای

برای ارائه فراگیرترین تجربه کاربری، ممکن است بخواهید فراتر از نمایش فراداده‌های اولیه در صفحه نمایش خودرو عمل کنید. با شروع از API سطح ۶ اپلیکیشن خودرو، اپلیکیشن‌های ناوبری این امکان را دارند که محتوای خود را مستقیماً روی صفحه نمایش (در خودروهای پشتیبانی‌شده) رندر کنند، البته با محدودیت‌های زیر:

  • API نمایش خوشه از کنترل‌های ورودی پشتیبانی نمی‌کند.
  • دستورالعمل کیفیت اپلیکیشن خودرو NF-9 : نمایشگر کلاستر باید فقط کاشی‌های نقشه را نشان دهد. یک مسیر ناوبری فعال می‌تواند به صورت اختیاری روی این کاشی‌ها نمایش داده شود.
  • API نمایش خوشه‌ای فقط از استفاده از NavigationTemplate پشتیبانی می‌کند.
    • برخلاف نمایشگرهای اصلی، نمایشگرهای خوشه‌ای ممکن است تمام عناصر رابط کاربری NavigationTemplate ، مانند دستورالعمل‌های گام به گام، کارت‌های ETA و اقدامات را به طور مداوم نشان ندهند. کاشی‌های نقشه تنها عنصر رابط کاربری هستند که به طور مداوم نمایش داده می‌شوند.

اعلام پشتیبانی از کلاستر

برای اینکه به برنامه میزبان اطلاع دهید که برنامه شما از رندرینگ در نمایشگرهای خوشه‌ای پشتیبانی می‌کند، باید عنصر androidx.car.app.category.FEATURE_CLUSTER <category> را به <intent-filter> مربوط به CarAppService خود اضافه کنید، همانطور که در قطعه کد زیر نشان داده شده است:

<application>
    ...
   <service
       ...
        android:name=".MyNavigationCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION"/>
        <category android:name="androidx.car.app.category.FEATURE_CLUSTER"/>
      </intent-filter>
    </service>
    ...
</application>

چرخه حیات و مدیریت وضعیت

با شروع از API سطح ۶، جریان چرخه عمر برنامه خودرو ثابت می‌ماند، اما اکنون CarAppService::onCreateSession پارامتری از نوع SessionInfo می‌گیرد که اطلاعات بیشتری در مورد Session ایجاد شده (یعنی نوع نمایش و مجموعه قالب‌های پشتیبانی شده) ارائه می‌دهد.

برنامه‌ها می‌توانند از یک کلاس Session برای مدیریت هر دو نمایشگر کلاستر و اصلی استفاده کنند، یا Sessions مخصوص نمایشگر ایجاد کنند تا رفتار هر نمایشگر را سفارشی‌سازی کنند (همانطور که در قطعه کد زیر نشان داده شده است). 

override fun onCreateSession(sessionInfo: SessionInfo): Session {
    return if (sessionInfo.displayType == SessionInfo.DISPLAY_TYPE_CLUSTER) {
        ClusterSession()
    } else {
        MainDisplaySession()
    }
}

هیچ تضمینی در مورد زمان یا نحوه ارائه نمایش خوشه‌ای وجود ندارد، و همچنین ممکن است که Session خوشه‌ای تنها Session باشد (برای مثال، کاربر در حالی که برنامه شما به طور فعال در حال پیمایش است، صفحه نمایش اصلی را به برنامه دیگری منتقل کرده است). توافق "استاندارد" این است که برنامه فقط پس از فراخوانی NavigationManager::navigationStarted کنترل نمایش خوشه‌ای را به دست می‌گیرد. با این حال، ممکن است نمایش خوشه‌ای در حالی که هیچ پیمایش فعالی رخ نمی‌دهد، به برنامه ارائه شود، یا هرگز نمایش خوشه‌ای به آن ارائه نشود. مدیریت این سناریوها با رندر کردن حالت بیکار کاشی‌های نقشه برنامه شما، به برنامه شما بستگی دارد.

میزبان به ازای هر Session نمونه‌های جداگانه‌ای از binder و CarContext ایجاد می‌کند. این بدان معناست که هنگام استفاده از متدهایی مانند ScreenManager::push یا Screen::invalidate ، فقط Session ای که از آن فراخوانی می‌شوند تحت تأثیر قرار می‌گیرد. در صورت نیاز به ارتباط بین Session (مثلاً با استفاده از broadcastها ، یک singleton مشترک یا موارد دیگر)، برنامه‌ها باید کانال‌های ارتباطی خود را بین این نمونه‌ها ایجاد کنند.

تست پشتیبانی کلاستر

شما می‌توانید پیاده‌سازی خود را هم روی Android Auto و هم روی Android Automotive OS آزمایش کنید. برای Android Auto، این کار با پیکربندی Desktop Head Unit برای شبیه‌سازی یک نمایشگر خوشه‌ای ثانویه انجام می‌شود. برای Android Automotive OS، تصاویر سیستم عمومی برای API سطح 30 و بالاتر، یک نمایشگر خوشه‌ای را شبیه‌سازی می‌کنند.

سفارشی‌سازی TravelEstimate با متن یا آیکون

برای سفارشی‌سازی تخمین سفر با متن، آیکون یا هر دو، از متدهای setTripIcon یا setTripText کلاس TravelEstimate.Builder استفاده کنید. NavigationTemplate از TravelEstimate برای تنظیم اختیاری متن و آیکون‌ها در کنار یا به جای زمان تخمینی رسیدن، زمان باقیمانده و مسافت باقیمانده استفاده می‌کند.

شکل ۱. تخمین سفر با آیکون و متن سفارشی.

قطعه کد زیر setTripIcon و setTripText برای سفارشی‌سازی تخمین سفر استفاده می‌کند: 

TravelEstimate.Builder(
    Distance.create(350.0, Distance.UNIT_METERS),
    arrivalTimeAtDestination
)
    .setTripIcon(
        CarIcon.Builder(
            IconCompat.createWithResource(carContext, R.drawable.ic_garage)
        ).build()
    )
    .setTripText(CarText.create("Custom Text"))
    .build()

ارائه اعلان‌های نوبتی

دستورالعمل‌های ناوبری گام به گام (TBT) را با استفاده از یک اعلان ناوبری که مرتباً به‌روزرسانی می‌شود، ارائه دهید. برای اینکه اعلان شما به عنوان یک اعلان ناوبری در صفحه نمایش خودرو در نظر گرفته شود، سازنده اعلان شما باید موارد زیر را انجام دهد:

  1. با استفاده از متد NotificationCompat.Builder.setOngoing ، اعلان را به عنوان در حال انجام علامت‌گذاری کنید.
  2. دسته بندی اعلان را روی Notification.CATEGORY_NAVIGATION تنظیم کنید.
  3. اعلان را با CarAppExtender گسترش دهید.

یک اعلان ناوبری در ویجت ریلی در پایین صفحه نمایش خودرو نمایش داده می‌شود. اگر سطح اهمیت اعلان روی IMPORTANCE_HIGH تنظیم شده باشد، به عنوان یک اعلان هشدار (HUN) نیز نمایش داده می‌شود. اگر اهمیت با متد CarAppExtender.Builder.setImportance تنظیم نشده باشد، از اهمیت کانال اعلان استفاده می‌شود.

برنامه می‌تواند یک PendingIntent در CarAppExtender تنظیم کند که وقتی کاربر روی HUN یا ویجت ریل ضربه می‌زند، به برنامه ارسال می‌شود.

اگر NotificationCompat.Builder.setOnlyAlertOnce با مقدار true فراخوانی شود، یک اعلان با اهمیت بالا فقط یک بار در HUN هشدار می‌دهد.

قطعه کد زیر نحوه ساخت یک اعلان ناوبری را نشان می‌دهد: 

NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    .setOnlyAlertOnce(true)
    .setOngoing(true)
    .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(carScreenTitle)
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_OPEN_APP.hashCode(),
                    Intent(ACTION_OPEN_APP).setComponent(
                        ComponentName(context, MyNotificationReceiver::class.java)
                    ),
                    PendingIntent.FLAG_IMMUTABLE
                )
            )
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build()
    )
    .build()

اعلان TBT را مرتباً برای تغییرات مسافت به‌روزرسانی کنید، که ویجت ریل را به‌روزرسانی می‌کند و فقط اعلان را به عنوان یک HUN نشان می‌دهد. می‌توانید رفتار HUN را با تنظیم اهمیت اعلان با CarAppExtender.Builder.setImportance کنترل کنید. تنظیم اهمیت روی IMPORTANCE_HIGH یک HUN را نشان می‌دهد. تنظیم آن روی هر مقدار دیگری فقط ویجت ریل را به‌روزرسانی می‌کند.

محتوای الگوی ناوبری لیست مکان را به‌روزرسانی کنید

شما می‌توانید به درایورها اجازه دهید هنگام مرور لیست مکان‌های ساخته شده با PlaceListNavigationTemplate ، با لمس یک دکمه، محتوا را به‌روزرسانی کنند. برای فعال کردن به‌روزرسانی لیست، متد onContentRefreshRequested از رابط OnContentRefreshListener را پیاده‌سازی کنید و PlaceListNavigationTemplate.Builder.setOnContentRefreshListener برای تنظیم شنونده روی قالب استفاده کنید.

قطعه کد زیر نحوه تنظیم شنونده (listener) روی قالب را نشان می‌دهد: 

PlaceListNavigationTemplate.Builder()
    .setOnContentRefreshListener {
        // Execute any desired logic
        // Then call invalidate() so onGetTemplate() is called again
        screen.invalidate()
    }
    .build()

دکمه‌ی refresh فقط در صورتی در هدر PlaceListNavigationTemplate نمایش داده می‌شود که listener دارای مقداری باشد.

وقتی کاربر روی دکمه‌ی refresh کلیک می‌کند، متد onContentRefreshRequested از پیاده‌سازی OnContentRefreshListener شما فراخوانی می‌شود. درون onContentRefreshRequested ، متد Screen.invalidate را فراخوانی کنید. سپس میزبان، متد Screen.onGetTemplate برنامه‌ی شما را فراخوانی می‌کند تا template را با محتوای refresh شده بازیابی کند. برای اطلاعات بیشتر در مورد refresh کردن templateها، به بخش Refresh the contents of a template مراجعه کنید. تا زمانی که template بعدی که توسط onGetTemplate برگردانده می‌شود از همان نوع باشد، به عنوان refresh محسوب می‌شود و در سهمیه‌ی template محاسبه نمی‌شود.

ارائه راهنمایی صوتی

برای پخش راهنمای ناوبری از بلندگوهای خودرو، برنامه شما باید درخواست فوکوس صوتی (audio focus) را بدهد. به عنوان بخشی از درخواست AudioFocusRequest ، مقدار استفاده را AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE قرار دهید. همچنین، میزان فوکوس (focus gain) را AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK قرار دهید.

شبیه‌سازی ناوبری

برای تأیید عملکرد ناوبری برنامه خود هنگام ارسال آن به فروشگاه Google Play، برنامه شما باید فراخوانی NavigationManagerCallback.onAutoDriveEnabled را پیاده‌سازی کند. هنگامی که این فراخوانی فراخوانی می‌شود، برنامه شما باید ناوبری را به مقصد انتخاب شده شبیه‌سازی کند، زمانی که کاربر ناوبری را شروع می‌کند. برنامه شما می‌تواند هر زمان که چرخه حیات Session فعلی به حالت Lifecycle.Event.ON_DESTROY برسد، از این حالت خارج شود.

شما می‌توانید با اجرای دستور زیر از خط فرمان، فراخوانی پیاده‌سازی onAutoDriveEnabled را بررسی کنید: 

adb shell dumpsys activity service CAR_APP_SERVICE_NAME AUTO_DRIVE

این در مثال زیر نشان داده شده است: 

adb shell dumpsys activity service androidx.car.app.samples.navigation.car.NavigationCarAppService AUTO_DRIVE

برنامه ناوبری پیش‌فرض خودرو

در اندروید اتو، برنامه ناوبری پیش‌فرض خودرو مطابق با آخرین برنامه ناوبری است که کاربر اجرا کرده است. برنامه پیش‌فرض زمانی که کاربر دستورات ناوبری را از طریق دستیار صوتی (Assistant) فراخوانی می‌کند یا زمانی که برنامه دیگری برای شروع ناوبری، اینتنت ارسال می‌کند، اینتنت‌های ناوبری را دریافت می‌کند .

نمایش هشدارهای ناوبری درون متنی

Alert اطلاعات مهم را با اقدامات اختیاری به راننده نمایش می‌دهد - بدون اینکه از صفحه ناوبری خارج شود. برای ارائه بهترین تجربه به راننده، Alert در NavigationTemplate کار می‌کند تا از مسدود شدن مسیر ناوبری جلوگیری کرده و حواس‌پرتی راننده را به حداقل برساند.

Alert فقط درون NavigationTemplate در دسترس است. برای اطلاع‌رسانی به کاربر خارج از NavigationTemplate ، همانطور که در Display notifications توضیح داده شده است، از یک اعلان هشدار (HUN) استفاده کنید.

برای مثال، Alert برای موارد زیر استفاده کنید:

  • راننده را از به‌روزرسانی‌های مربوط به ناوبری فعلی، مانند تغییر در شرایط ترافیک، مطلع کنید.
  • از راننده بخواهید به‌روزرسانی‌هایی مربوط به ناوبری فعلی، مانند وجود سرعت‌گیر، ارائه دهد.
  • یک کار پیشنهادی برای آینده پیشنهاد دهید و بپرسید که آیا راننده آن را می‌پذیرد یا خیر، مثلاً آیا راننده حاضر است در مسیر خود کسی را سوار کند یا خیر.

در شکل اولیه، یک Alert شامل یک عنوان و مدت زمان Alert است. مدت زمان هشدار توسط یک نوار پیشرفت نمایش داده می‌شود. به صورت اختیاری، می‌توانید یک زیرنویس، یک آیکون و حداکثر دو شیء Action اضافه کنید.

شکل ۲. هشدار ناوبری درون متنی.

زمانی که یک Alert نمایش داده می‌شود، اگر تعامل راننده منجر به خروج از NavigationTemplate شود، به الگوی دیگری منتقل نمی‌شود. این هشدار در NavigationTemplate اصلی باقی می‌ماند تا زمانی که زمان Alert به پایان برسد، کاربر اقدامی انجام دهد یا برنامه Alert رد کند.

ایجاد هشدار

Alert.Builder برای ایجاد یک نمونه Alert استفاده کنید: 

Alert.Builder(
    1, // alertId
    CarText.create("Hello"), // title
    5000 // durationMillis
)
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create("Subtitle"))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(alertCallback)
    .build()

اگر می‌خواهید لغو یا رد Alert را بررسی کنید، یک پیاده‌سازی از رابط AlertCallback ایجاد کنید. مسیرهای فراخوانی AlertCallback عبارتند از:

  • اگر زمان Alert به پایان برسد، میزبان متد AlertCallback.onCancel را با مقدار AlertCallback.REASON_TIMEOUT فراخوانی می‌کند. سپس متد AlertCallback.onDismiss را فراخوانی می‌کند.

  • اگر درایور روی یکی از دکمه‌های اکشن کلیک کند، میزبان Action.OnClickListener را فراخوانی می‌کند و سپس AlertCallback.onDismiss را فراخوانی می‌کند.

  • اگر Alert پشتیبانی نشود، میزبان AlertCallback.onCancel را با مقدار AlertCallback.REASON_NOT_SUPPORTED فراخوانی می‌کند. میزبان AlertCallback.onDismiss را فراخوانی نمی‌کند، زیرا Alert نمایش داده نشده است.

مدت زمان هشدار را پیکربندی کنید

مدت زمان Alert را متناسب با نیازهای برنامه خود انتخاب کنید. مدت زمان توصیه شده برای Alert ناوبری 10 ثانیه است. برای اطلاعات بیشتر به هشدارهای ناوبری مراجعه کنید.

نمایش هشدار

برای نمایش یک Alert ، متد AppManager.showAlert را که از طریق CarContext برنامه شما در دسترس است، فراخوانی کنید. 

carContext.getCarService(AppManager::class.java).showAlert(alert)

  • فراخوانی showAlert با Alert که alertId آن با شناسه Alert نمایش داده شده یکسان است، هیچ کاری انجام نمی‌دهد. Alert به‌روزرسانی نمی‌شود. برای به‌روزرسانی یک Alert ، باید آن را با یک alertId جدید از نو ایجاد کنید.
  • فراخوانی showAlert با Alert که alertId متفاوتی نسبت به Alert نمایش داده شده دارد، هشدار نمایش داده شده توسط Alert را رد می‌کند.

رد کردن هشدار

اگرچه یک Alert به دلیل وقفه زمانی یا تعامل با درایور به طور خودکار رد می‌شود، اما می‌توانید به صورت دستی نیز یک Alert رد کنید، مثلاً اگر اطلاعات آن قدیمی شده باشد. برای رد کردن یک Alert ، متد dismissAlert را با alertId مربوط به Alert فراخوانی کنید. 

carContext.getCarService(AppManager::class.java).dismissAlert(alert.id)

فراخوانی dismissAlert با alertId که با Alert نمایش داده شده مطابقت ندارد، هیچ کاری انجام نمی‌دهد. هیچ استثنایی ایجاد نمی‌کند.