إنشاء تطبيق للتنقّل

تعرض هذه الصفحة تفاصيل الميزات المختلفة لـ Car App Library التي يمكنك استخدامها لتنفيذ وظائف تطبيق التنقّل باتّجاهات مفصّلة.

توضيح إتاحة التنقّل في البيان

يجب أن يذكر تطبيق التنقّل androidx.car.app.category.NAVIGATION فئة تطبيق السيارة في فلتر الأهداف في 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>

أهداف التنقّل في الدعم

لإتاحة أغراض التنقّل إلى تطبيقك، بما في ذلك تلك الواردة من "مساعد Google" باستخدام طلب صوتي، يجب أن يعالج تطبيقك هدف CarContext.ACTION_NAVIGATE في Session.onCreateScreen وSession.onNewIntent.

اطّلِع على المستندات بشأن CarContext.startCarApp للحصول على تفاصيل عن تنسيق الغرض.

الوصول إلى نماذج التنقل

يمكن لتطبيقات التنقل الوصول إلى النماذج التالية المصممة خصيصًا لتطبيقات التنقل. تعرض كل هذه القوالب سطحًا في الخلفية مع الخريطة والاتجاهات المفصّلة أثناء التنقل النشط.

• NavigationTemplate: يعرض أيضًا رسالة إعلامية اختيارية وتقديرات بشأن السفر أثناء التنقّل النشط.
• MapTemplate: تقدّم نسخة مصغّرة من قائمة (كما في ListTemplate) أو من جزء (معلومات مفصّلة مع إجراءات بارزة، كما في PaneTemplate) بجانب خريطة.
• PlaceListNavigationTemplate: يعرض أيضًا قائمة بالأماكن التي يمكن أن تكون لها علامات مقابلة مرسومة في الخريطة.
• RoutePreviewNavigationTemplate: يعرض أيضًا قائمة بالمسارات، ويمكن اختيار أحدها وتمييزه في الخريطة.

للحصول على مزيد من التفاصيل عن كيفية تصميم واجهة مستخدم تطبيق التنقّل باستخدام تلك النماذج، يمكنك الاطّلاع على تطبيقات التنقّل.

للوصول إلى نماذج التنقّل، يجب أن يوضِّح تطبيقك إذن androidx.car.app.NAVIGATION_TEMPLATES في ملف AndroidManifest.xml:

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

رسم الخريطة

يمكن لتطبيقات التنقّل الوصول إلى Surface لرسم الخريطة على النماذج ذات الصلة.

يمكن بعد ذلك الوصول إلى عنصر SurfaceContainer من خلال ضبط مثيل SurfaceCallback في خدمة السيارات AppManager:

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

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

يمكن للمضيف رسم عناصر واجهة المستخدم للنماذج أعلى الخريطة. يُبلغ المضيف عن المنطقة التي يمكن ضمان عدم وجود عوائق فيها ورؤيتها بالكامل للمستخدم من خلال استدعاء الطريقة SurfaceCallback.onVisibleAreaChanged. لتقليل عدد التغييرات أيضًا، يستدعي المضيف الطريقة SurfaceCallback.onStableAreaChanged بأصغر مستطيل، والذي يظهر دائمًا استنادًا إلى النموذج الحالي.

على سبيل المثال، عندما يستخدم أحد تطبيقات التنقّل NavigationTemplate مع شريط إجراءات في أعلى الشاشة، يمكن أن يخفي شريط الإجراءات نفسه عندما لا يتفاعل المستخدم مع الشاشة لفترة من الوقت لتوفير مساحة أكبر على الخريطة. في هذه الحالة، هناك معاودة اتصال إلى onStableAreaChanged وonVisibleAreaChanged باستخدام المستطيل نفسه. عند إخفاء شريط الإجراءات، يتم استدعاء onVisibleAreaChanged فقط مع المساحة الأكبر. إذا تفاعل المستخدم مع الشاشة، فسيتم مرة أخرى استدعاء onVisibleAreaChanged فقط مع المستطيل الأول.

إتاحة "الوضع الداكن"

على تطبيقات التنقّل إعادة رسم الخريطة على مثيل Surface باستخدام الألوان الداكنة المناسبة عندما يقرّر المضيف أنّ الظروف تتطلّب ذلك، على النحو الموضَّح في جودة تطبيقات Android للسيارات.

لتحديد ما إذا كنت تريد رسم خريطة داكنة أم لا، يمكنك استخدام الإجراء CarContext.isDarkMode. وعندما تتغيّر حالة "الوضع الداكن"، ستتلقّى مكالمة على الرقم Session.onCarConfigurationChanged.

نقل البيانات الوصفية للتنقُّل

يجب أن تقوم تطبيقات التنقل بتوصيل بيانات وصفية إضافية للتنقل مع المضيف. يستخدم المضيف المعلومات لتقديم معلومات إلى الوحدة الرئيسية للمركبة ولمنع تطبيقات التنقّل من التضارب مع الموارد المشتركة.

يتم توفير البيانات الوصفية للتنقُّل من خلال خدمة السيارات NavigationManager التي يمكن الوصول إليها من CarContext:

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

NavigationManager navigationManager = carContext.getCarService(NavigationManager.class);

بدء التنقّل وإنهائه وإيقافه

لكي يتمكن المضيف من إدارة العديد من تطبيقات التنقل وإشعارات التوجيه وبيانات مجموعة المركبات، يجب أن يكون على دراية بحالة التنقل الحالية. عندما يبدأ أحد المستخدمين التنقّل، اتّصِل بـ NavigationManager.navigationStarted. وبالمثل، عند انتهاء التنقّل، مثلاً عندما يصل المستخدم إلى وجهته أو عندما يلغي المستخدم التنقّل، يمكنك استدعاء NavigationManager.navigationEnded.

اتصل بـ NavigationManager.navigationEnded فقط عندما ينتهي المستخدم من التنقل. على سبيل المثال، إذا كنت بحاجة إلى إعادة احتساب المسار في منتصف الرحلة، استخدِم Trip.Builder.setLoading(true) بدلاً من ذلك.

أحيانًا، يحتاج المضيف إلى تطبيق لإيقاف التنقّل والمكالمات بـ onStopNavigation في عنصر NavigationManagerCallback يوفّره تطبيقك من خلال NavigationManager.setNavigationManagerCallback. يجب أن يتوقف التطبيق بعد ذلك عن إصدار معلومات الانعطاف التالي في عرض المجموعة وإشعارات التنقّل والإرشاد الصوتي.

تعديل معلومات الرحلة

أثناء التنقل النشِط، اتصِل بالرقم NavigationManager.updateTrip. يمكن استخدام المعلومات المقدمة في هذا الاستدعاء من خلال شاشات العرض الرأسية والتجميع العنقودي للمركبة. اعتمادًا على المركبة المحددة التي يتم قيادتها، لا يتم عرض كل المعلومات للمستخدم. على سبيل المثال، تعرض وحدة Desktop Head Unit (DHU) عنصر Step الذي تمت إضافته إلى Trip، ولكنّه لا يعرض معلومات Destination.

الرسم على العرض العنقودي

لتوفير تجربة المستخدم الأكثر شمولية، يمكنك استخدام ما هو أكثر من عرض البيانات الوصفية الأساسية على الشاشة المجمّعة للمركبة. بدءًا من المستوى 6 من Car App API، يتوفّر لتطبيقات التنقّل خيار عرض المحتوى الخاص بها مباشرةً على شاشة المجموعة (في المركبات المتوافقة)، مع القيود التالية:

• لا تتيح واجهة برمجة تطبيقات العرض العنقودية استخدام عناصر التحكم في الإدخال.
• من المفترض أن يعرض عرض المجموعة مربّعات الخرائط فقط. يمكن عرض التنقل النشط في المسار اختياريًا في هذه الفئات.
• تتيح واجهة برمجة تطبيقات عرض المجموعة استخدام NavigationTemplate
  فقط
  • على عكس الشاشات الرئيسية، قد لا تعرض الشاشات العنقودية بشكل متّسق جميع عناصر واجهة المستخدم في NavigationTemplate، مثل التعليمات المفصّلة وبطاقات الوقت المقدّر للوصول والإجراءات. تعد مربعات الخرائط هي عنصر واجهة المستخدم الوحيد المعروض بشكل متسق.

توضيح دعم المجموعة

لإعلام التطبيق المضيف بأنّ تطبيقك يتيح العرض على شاشات العرض المجمّعة، يجب إضافة العنصر 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>

إدارة الحالة ومراحل النشاط التجاري

بدءًا من المستوى السادس من واجهة برمجة التطبيقات، يظل مسار نشاط تطبيق السيارة كما هو، أما الآن، فيأخذ CarAppService::onCreateSession معلَمة من النوع SessionInfo توفّر معلومات إضافية عن Session التي يتم إنشاؤها (أي نوع الشاشة ومجموعة النماذج المتوافقة).

يتوفّر للتطبيقات خيار استخدام الفئة Session نفسها للتعامل مع المجموعة والشاشة الرئيسية على حد سواء، أو إنشاء Sessions لعرض تخصيص السلوك على كل شاشة (كما هو موضّح في المقتطف التالي).

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

@Override
@NonNull
public Session onCreateSession(@NonNull SessionInfo sessionInfo) {
  if (sessionInfo.getDisplayType() == SessionInfo.DISPLAY_TYPE_CLUSTER) {
    return new ClusterSession();
  } else {
    return new MainDisplaySession();
  }
}

وما من ضمانات بشأن وقت توفير عرض المجموعة أو إمكانية توفيره، ومن الممكن أيضًا أن تكون المجموعة Session هي Session الوحيدة (على سبيل المثال، قام المستخدم بتبديل الشاشة الرئيسية بتطبيق آخر أثناء تنقّل التطبيق بنشاط). تكمن الاتفاقية "العادية" في أنّه لا يمكن للتطبيق التحكّم في عرض المجموعة إلا بعد طلب NavigationManager::navigationStarted. ومع ذلك، من الممكن أن يتم توفير عرض المجموعة للتطبيق في حين عدم إجراء تنقل نشط، أو عدم توفير عرض المجموعة مطلقًا. الأمر متروك لتطبيقك للتعامل مع هذه السيناريوهات من خلال عرض حالة عدم نشاط التطبيق لمربّعات الخرائط.

ينشئ المضيف أداة ربط منفصلة وCarContext مثيل لكل Session. وهذا يعني أنّه عند استخدام طرق مثل ScreenManager::push أو Screen::invalidate، لن يتأثر سوى Session الذي تم استخدامها. يجب أن تنشئ التطبيقات قنوات التواصل الخاصة بها بين هذه الحالات في حال الحاجة إلى التواصل بين أكثر من Session (على سبيل المثال، من خلال استخدام عمليات البث أو مفردات مشتركة أو أي محتوى آخر).

دعم مجموعة الاختبار

يمكنك اختبار عملية التنفيذ على كل من Android Auto ونظام التشغيل Android Automotive. وبالنسبة إلى Android Auto، يتم إجراء ذلك من خلال ضبط الوحدة الرئيسية لسطح المكتب لمحاكاة شاشة العرض العنقودية الثانوية. بالنسبة إلى نظام التشغيل Android Automotive، فإنّ صور النظام العامة للمستوى 30 من واجهة برمجة التطبيقات والمستويات الأعلى تحاكي عرض مجموعة.

تخصيص TravelEstimate باستخدام نص أو رمز

لتخصيص الوقت المقدّر للسفر باستخدام نص أو رمز أو كليهما، استخدِم طريقة TravelEstimate.Builder للفئة setTripIcon أو setTripText. تستخدم NavigationTemplate TravelEstimate لضبط النص والرموز بشكل اختياري إلى جانب الوقت المقدّر للوصول والوقت المتبقي والمسافة المتبقية أو بدلاً منها.

يستخدم المقتطف التالي setTripIcon وsetTripText لتخصيص تقديرات السفر:

TravelEstimate.Builder(Distance.create(...), DateTimeWithZone.create(...))
      ...
      .setTripIcon(CarIcon.Builder(...).build())
      .setTripText(CarText.create(...))
      .build()

new TravelEstimate.Builder(Distance.create(...), DateTimeWithZone.create(...))
      ...
      .setTripIcon(CarIcon.Builder(...).build())
      .setTripText(CarText.create(...))
      .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)),
                        0))
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build())
    .build()

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

احرص على تحديث إشعار TBT بانتظام لمعرفة تغييرات المسافة، الذي يؤدي إلى تحديث التطبيق المصغّر للسكك الحديدية وعرض الإشعار على شكل HUN فقط. يمكنك التحكّم في سلوك HUN من خلال ضبط مدى أهمية الإشعار باستخدام CarAppExtender.Builder.setImportance. يؤدي ضبط الأهمية على IMPORTANCE_HIGH إلى إظهار HUN. يؤدي تعيينه على أي قيمة أخرى إلى تحديث أداة السكك الحديدية فقط.

إعادة تحميل محتوى PlaceList NavigationTemplate

يمكنك السماح للسائقين بإعادة تحميل المحتوى بنقرة زر واحدة أثناء تصفُّح قوائم الأماكن التي تم إنشاؤها باستخدام PlaceListNavigationTemplate. لتفعيل ميزة إعادة تحميل القائمة، عليك تنفيذ طريقة OnContentRefreshListener الواجهة onContentRefreshRequested واستخدام PlaceListNavigationTemplate.Builder.setOnContentRefreshListener لضبط أداة معالجة الحدث على النموذج.

يوضّح المقتطف التالي كيفية تعيين أداة الاستماع إلى النموذج:

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

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

لا يظهر زر إعادة التحميل في عنوان PlaceListNavigationTemplate إلا إذا كان للمستمع قيمة.

عندما ينقر المستخدم على زر إعادة التحميل، يتم استدعاء طريقة onContentRefreshRequested لتنفيذ OnContentRefreshListener. ضمن onContentRefreshRequested، استدعِ الطريقة Screen.invalidate. بعد ذلك، يستدعي المضيف طريقة Screen.onGetTemplate في تطبيقك لاسترداد النموذج الذي يتضمّن المحتوى الذي تم تحديثه. يمكنك الاطّلاع على إعادة تحميل محتوى نموذج للحصول على مزيد من المعلومات حول إعادة تحميل النماذج. ما دام النموذج التالي الذي تم عرضه بواسطة onGetTemplate من النوع نفسه، يتم احتسابه كإعادة تحميل ولا يتم احتسابه ضمن حصة النموذج.

تقديم الإرشادات الصوتية

لتشغيل إرشادات التنقّل عبر مكبّرات الصوت في السيارة، يجب أن يطلب التطبيق التركيز على الصوت. كجزء من AudioFocusRequest، اضبط الاستخدام على AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE. يمكنك أيضًا ضبط زيادة التركيز على 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

تطبيق التنقّل التلقائي للسيارة

في Android Auto، يتوافق تطبيق التنقل التلقائي في السيارة مع آخر تطبيق تنقّل أطلقه المستخدم. ويتلقّى التطبيق التلقائي أهداف التنقّل عندما يستدعي المستخدِم أوامر التنقّل من خلال "مساعد Google" أو عندما يرسِل تطبيق آخر هدفًا لبدء التنقّل.

السماح للمستخدمين بالتفاعل مع خريطتك

يمكنك إضافة دعم للمستخدمين للتفاعل مع الخرائط، مثل السماح لهم بمشاهدة أجزاء مختلفة من الخريطة عن طريق التكبير والتصغير والتحريك. يحتوي كل نموذج على حد أدنى مختلف لمتطلبات مستوى واجهة برمجة تطبيقات Car App API. راجع الجدول التالي لمعرفة الحد الأدنى للمستوى للقالب الذي تريد تنفيذه.

طرق معاودة الاتصال في Surface

تتضمن واجهة SurfaceCallback عدة طرق لمعاودة الاتصال تتيح لك إضافة تفاعل إلى الخرائط التي تم إنشاؤها باستخدام نماذج NavigationTemplate أو PlaceListNavigationTemplate أو RoutePreviewNavigationTemplate أو MapTemplate: onClick وonScroll وonScale وonFling. راجِع الجدول التالي لمعرفة مدى صلة عمليات معاودة الاتصال هذه بتفاعلات المستخدم.

شريط الإجراءات على الخريطة

يمكن أن تحتوي نماذج NavigationTemplate وPlaceListNavigationTemplate وRoutePreviewNavigationTemplate وMapTemplate على شريط إجراءات على الخريطة لتنفيذ الإجراءات المتعلقة بالخريطة، مثل التكبير والتصغير وإعادة التوسيط وعرض بوصلة والإجراءات الأخرى التي تختار عرضها. يمكن أن يحتوي شريط إجراءات الخريطة على ما يصل إلى أربعة أزرار على شكل رموز فقط يمكن تحديثها بدون التأثير على عمق المهمة. كما يختبئ أثناء حالة الخمول ويظهر مرة أخرى في حالة النشاط.

لتلقّي طلبات إعادة الاتصال للتفاعل على الخريطة، يجب إضافة الزر Action.PAN في شريط إجراءات الخريطة. عندما يضغط المستخدم على زر التحريك، يدخل المضيف في وضع العرض الشامل، كما هو موضح في القسم التالي.

إذا حذف تطبيقك الزر Action.PAN في شريط إجراءات الخريطة، لن يتلقّى إدخالات المستخدم من طرق SurfaceCallback ويخرج المضيف من أي وضع عرض شامل سبق تفعيله.

على شاشة تعمل باللمس، لا يتم عرض زر العرض الشامل.

وضع العرض الشامل

في وضع العرض الشامل، يترجم مضيف النموذج البيانات التي أدخلها المستخدم من أجهزة الإدخال التي لا تعمل باللمس، مثل وحدات التحكّم في الدوران ولوحات اللمس، إلى طرق SurfaceCallback المناسبة. يمكنك الاستجابة لإجراء المستخدم للدخول في وضع العرض الشامل أو الخروج منه باستخدام الطريقة setPanModeListener في NavigationTemplate.Builder. يمكن للمضيف إخفاء مكونات واجهة المستخدم الأخرى في القالب عندما يكون المستخدم في وضع العرض الشامل.

منطقة ثابتة

يتم تعديل المنطقة الثابتة بين حالتَي "عدم النشاط" و"وضع عدم النشاط". حدد ما إذا كنت تريد رسم المعلومات المتعلقة بالقيادة، مثل السرعة أو حد السرعة أو التحذيرات على الطريق، بناءً على حجم المنطقة الثابتة، بحيث لا يتم حجب المعلومات المهمة على الخريطة بواسطة شريط إجراءات الخريطة.

عرض تنبيهات التنقّل في السياق

Alert يعرض معلومات مهمة للسائق من خلال إجراءات اختيارية، وذلك بدون مغادرة سياق شاشة التنقّل. لتوفير أفضل تجربة للسائق، تعمل ميزة Alert ضمن NavigationTemplate لتجنُّب حظر مسار التنقّل وتقليل تشتت انتباه السائق.

يتوفّر "Alert" فقط ضمن NavigationTemplate. لإبلاغ المستخدم خارج نطاق NavigationTemplate، يمكنك استخدام إشعار تنبيه (HUN)، كما هو موضّح في عرض الإشعارات.

على سبيل المثال، يمكنك استخدام Alert لإجراء ما يلي:

• قم بإبلاغ السائق بتحديث ذي الصلة بالتنقل الحالي، مثل تغيير ظروف حركة المرور.
• اطلب من السائق تعديل المعلومات ذات الصلة بميزة التنقّل الحالية، مثل وجود رادار سرعة متنقّل.
• اقترح مهمة قادمة واسأل ما إذا كان السائق يقبلها، مثل ما إذا كان السائق على استعداد لاصطحاب شخص ما في طريقه.

يتكوّن Alert في شكله الأساسي من عنوان ومدّة Alert. يتم تمثيل مدة المدة بشريط تقدم. يمكنك اختياريًا إضافة عنوان فرعي ورمز وما يصل إلى عنصرَين من عناصر Action.

بعد عرض Alert، لا يتم نقله إلى نموذج آخر إذا كان تفاعل السائق يؤدي إلى مغادرة NavigationTemplate. يبقى الرمز في NavigationTemplate الأصلي حتى انتهاء مهلة Alert أو يتّخذ المستخدم إجراءً أو يرفض التطبيق Alert.

إنشاء تنبيه

استخدِم Alert.Builder لإنشاء مثيل Alert:

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

new Alert.Builder(
        /*alertId*/ 1,
        /*title*/ CarText.create("Hello"),
        /*durationMillis*/ 5000
    )
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create(...))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(...)
    .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 في تطبيقك.

// Show an alert
carContext.getCarService(AppManager.class).showAlert(alert)

• إنّ طلب showAlert باستخدام Alert يتضمّن alertId مماثل لمعرّف Alert المعروض حاليًا ليس مفيدًا. ولا يتم تعديل "Alert". لتعديل Alert، عليك إعادة إنشائه باستخدام عنصر alertId جديد.
• في حال استدعاء showAlert باستخدام Alert الذي يحتوي على alertId مختلف عن Alert المعروض حاليًا، يتم إغلاق Alert المعروضة حاليًا.

إغلاق تنبيه

على الرغم من أنّه يتم إغلاق Alert تلقائيًا بسبب انتهاء المهلة أو تفاعل السائق، يمكنك أيضًا إغلاق Alert يدويًا، مثلاً إذا أصبحت معلوماته قديمة. لإغلاق Alert، عليك استدعاء الإجراء dismissAlert مع alertId في Alert.

// Dismiss the same alert
carContext.getCarService(AppManager.class).dismissAlert(alert.getId())

إنّ الاتصال بـ dismissAlert باستخدام alertId لا يتطابق مع Alert المعروض حاليًا، لن يؤدي إلى أي نتيجة. ولا يقدم استثناءً.