החל מ-27 במרץ 2025, מומלץ להשתמש ב-android-latest-release במקום ב-aosp-main כדי ליצור תרומות ל-AOSP. מידע נוסף זמין במאמר שינויים ב-AOSP.
הגדרת מארח של AppCard
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
אפשר להשתמש ב-AppCardHost כדי לתקשר עם אפליקציות שמוצגות בהן כרטיסי אפליקציות.
הרשאות
לכל אפליקציה שמשתמשת ב-AppCardHost צריכות להיות ההרשאות הבאות:
android.permission.INTERACT_ACROSS_USERS_FULLandroid.permission.QUERY_ALL_PACKAGES- (ברמת API 34 ואילך בלבד)
android.car.permission.BIND_APP_CARD_PROVIDER
התחל
כדי לאתחל את המארח, צריך לספק את הפרטים הבאים:
- הקשר
- שיעור העדכון של
updateRate AppCard באלפיות השנייה.
fastUpdateRate קצב העדכון באלפיות השנייה לרכיבים שמסומנים בתג EnforceFastUpdateRateresponseExecutor שרשור שבו רוצים לקבל תשובות מאפליקציות AppCard.
עיצוב
אפשר לבצע פעולות עם AppCardHost בשתי דרכים:
או
AppCardListener
הרכיב AppCardListener מתעדכן ב-AppCardHost כדי לקבל עדכוני תקשורת מאפליקציית AppCardHost ומ-AppCard.
כאן מפורטות פונקציות הממשק של AppCardListener.
fun onAppCardReceived(AppCardContainer)
הפונקציה הזו מופעלת כשמתקבלת כרטיס אפליקציה מאפליקציה. היא נשלחת כ-AppCardContainer שמספק כרטיס אפליקציה ו-appIdentifier כדי לזהות את האפליקציה ששלחה את כרטיס האפליקציה
fun onComponentReceived(AppCardComponentContainer)
הפונקציה הזו מופעלת כשמקבלים רכיב של כרטיס אפליקציה מאפליקציה. הוא נשלח כ-AppCardComponentContainer, שמספק רכיב של כרטיסי אפליקציה, Identifier, כדי לזהות את האפליקציה ששלחה את כרטיס האפליקציה, ומזהה מחרוזת כדי להצביע על כרטיס האפליקציה שאליו הרכיב קשור.
fun onProviderRemoved(String, String?)
הפונקציה הזו מופעלת כשספק של כרטיס AppCard הוסר או הושבת. משתמשים בשיטה הזו כדי לנקות כל כרטיס AppCard פעיל שקשור לשם החבילה ולסמכות הספק שצוינו.
אם הערך של authority הוא {@code null}, המשמעות היא שהחבילה כולה הוסרה.
fun onProviderAdded(String, String?)
הפונקציה הזו מופעלת כשספק של כרטיס AppCard נוסף או מופעל.
דוגמה לשימוש אפשר להשתמש בפונקציה הזו כטריגר כדי לרענן את כל כרטיסי האפליקציות הזמינים בבורר של כרטיסי האפליקציות. אם הערך של authority הוא {@code null}, המשמעות היא שנוספה חבילה שלמה.
fun onPackageCommunicationError(appIdentifier, Throwable)
הפונקציה הזו מופעלת כש-AppCardHost נתקל בשגיאה בתקשורת עם ספק של כרטיס AppCard.
דוגמה לשימוש משתמשים בשיטה הזו כדי להציג למשתמש שהתרחשה שגיאה ב-AppCard שבחר.
ממשקי API
fun refreshCompatibleapp()
צריך לקרוא למתודה הזו בכל פעם שהפעילות שמשתמשת במארח ממשיכה, כדי שהמארח יוכל לרענן את רשימת האפליקציות שתומכות ב-AppCards.
fun destroy()
צריך להפעיל את השיטה הזו כשפעילות שמשתמשת במארח נהרסת, כדי שהמארח יוכל לנקות את כל החיבורים והחברים הפנימיים.
fun registerListener(AppCardListener)
משמש לרישום AppCardListener.
fun unregisterListener(AppCardListener)
משמשת לביטול הרישום של AppCardListener.
fun getAllAppCards(AppCardContext)
קוראים ל-method הזה כדי לספק ל-AppCardListener הרשום את כל כרטיסי ה-AppCard שסופקו במערכת עם AppCardContext נתון, שמספק לספקים טיפים לגבי מבנה של כרטיס ה-AppCard שלהם.
fun requestAppCard(AppCardContext, appIdentifier, String)
קוראים לשיטה הזו כדי לספק ל-AppCardListener רשום AppCard ספציפי, על סמך AppCardContext שמספק לספקים טיפים לגבי מבנה ה-AppCard שלהם.
fun notifyAppCardRemoved(appIdentifier, String)
איך מודיעים לספק של כרטיס AppCard שהכרטיס לא פעיל יותר
fun notifyAppCardInteraction(appIdentifier, String, String, String)
לדווח לספק של כרטיס AppCard על אינטראקציה עם כרטיס AppCard שלו.
האינטראקציה היחידה שנתמכת היא לחיצה על לחצן, שמסומנת ב-AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK.
מומלץ ליצור לחצן ל-AppCard עם מאזין onClick שמפעיל את הפונקציה הזו עם appIdentifier, מזהה AppCard, מזהה רכיב ומזהה אינטראקציה.
fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)
שליחת עדכון AppCardContext של כרטיס אפליקציה ספציפי. לדוגמה, כשעוברים ממצב 'חניה' למצב 'נסיעה', משתמשים בשיטה הזו כדי לשלוח עדכון AppCardContext שבו isInteractable מוגדר ל-false לכל כרטיס אפליקציה פעיל.
שאלות נפוצות
איפה אפשר למצוא הטמעות לדוגמה?
מארח לדוגמה. כאן מוצגות כל כרטיסי האפליקציות שזמינים במערכת, יחד עם יכולות הבדיקה.
DriverUI ו-Pano Manager. מנהל Pano פועל בתור הבורר, ו-DriverUI פועל בתור המציג.
כמה כרטיסי אפליקציה כל AppCardContentProvider יכול לתמוך?
AppCardContentProvider יכול לתמוך במספר אינסופי של כרטיסי אפליקציה.
עם זאת, חשוב לאזן בין מספר כרטיסי האפליקציות לבין פגיעה בביצועים לעומת חוויית משתמש חיובית.
דוגמאות התוכן והקוד שבדף הזה כפופות לרישיונות המפורטים בקטע רישיון לתוכן. Java ו-OpenJDK הם סימנים מסחריים או סימנים מסחריים רשומים של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-06-26 (שעון UTC).
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2025-06-26 (שעון UTC)."],[],[],null,["# Configure an AppCard host\n\nUse `AppCardHost` to communicate with apps that show AppCards.\n\nPermissions\n-----------\n\nAny app that uses an `AppCardHost` must have the following permissions:\n\n- `android.permission.INTERACT_ACROSS_USERS_FULL`\n- `android.permission.QUERY_ALL_PACKAGES`\n- (In API level 34 and higher **only** ) `android.car.permission.BIND_APP_CARD_PROVIDER`\n\nInitialize\n----------\n\nTo initialize the host, provide:\n\n- Context\n- `updateRate` AppCard update rate in milliseconds.\n- `fastUpdateRate` Update rate in milliseconds for components tagged with `EnforceFastUpdateRate`\n- `responseExecutor` A thread on which you want to receive responses from AppCard apps.\n\nDesign\n------\n\nAn `AppCardHost` can be interacted with in one of two ways:\n\n- Register as an [`AppCardListener`](#appcardlistener)\n\nOR,\n\n- Interact with the [`AppCardHost` APIs](#api)\n\n### AppCardListener\n\nThe `AppCardListener` component registers itself with an `AppCardHost`\nto receive communication updates from the `AppCardHost` and AppCard apps.\nThe interface functions of an `AppCardListener` are detailed here.\n\n\u003cbr /\u003e\n\n`fun onAppCardReceived(AppCardContainer)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard has been received from an app. It's sent as an `AppCardContainer` which provides an AppCard and an `appIdentifier` to identify the app that sent the AppCard\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onComponentReceived(AppCardComponentContainer)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard component is received from an app. It's sent as an `AppCardComponentContainer`, which provides an AppCards component, `Identifier` to identify the app that sent the AppCard, and a string ID to point to the AppCard to which the component is related.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onProviderRemoved(String, String?)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard provider has been removed or disabled. Use this method to clean up any active AppCard related to the given package name and provider authority.\u003cbr /\u003e\n\nIf authority is `{@code null}`, then an entire package was removed.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onProviderAdded(String, String?)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when an AppCard provider has been added or enabled.\u003cbr /\u003e\n\n**Sample usage.** Use this function as a trigger to refresh all available\nAppCards in an AppCard picker. If authority is `{@code null}`, then an entire\npackage was added.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun onPackageCommunicationError(appIdentifier, Throwable)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis function is triggered when the `AppCardHost` encounters an error when communicating with an AppCard provider.\n\n\u003cbr /\u003e\n\n**Sample usage.** Use this method to show to the user that an AppCard they have\nselected has encountered an error.\n\n\u003cbr /\u003e\n\n### APIs\n\n\u003cbr /\u003e\n\n`fun refreshCompatibleapp()`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis method should be called whenever the activity that is using the host is resumed so that the host can refresh its list of apps that support AppCards.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun destroy()`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCall this method when an activity that is using a host is destroyed so that the host can clean up all connections and internal members.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun registerListener(AppCardListener)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nUsed to register an `AppCardListener`.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun unregisterListener(AppCardListener)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nUsed to unregister an `AppCardListener`.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun getAllAppCards(AppCardContext)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCall this method to supply a registered `AppCardListener` with all the AppCards provided in the system with a given `AppCardContext` that provides hints to the providers on how to structure their AppCard.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun requestAppCard(AppCardContext, appIdentifier, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCall this method to supply a registered `AppCardListener` with a specific AppCard, given an `AppCardContext` that gives hints to the providers on how to structure their AppCard.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun notifyAppCardRemoved(appIdentifier, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nNotify an AppCard provider that its AppCard is no longer active.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun notifyAppCardInteraction(appIdentifier, String, String, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nNotify an AppCard provider that its AppCard has been interacted with. The only supported interaction is a button click, which is signified by a `AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK`.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nWe recommend creating a button for an AppCard with an `onClick` listener that calls this function with `appIdentifier`, AppCard ID, component ID, and interaction ID.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n`fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nSend an `AppCardContext` update for a specific AppCard. For example, when shifting from Park mode to Drive mode, use this method to send an `AppCardContext` update in which `isInteractable` is set to `false` for each active AppCard.\n\n\u003cbr /\u003e\n\nFAQ\n---\n\n1. Where can I find sample implementations?\n\n - [Sample host](https://android.googlesource.com/platform/packages/apps/Car/libs/+/refs/tags/ub-automotive-master-20250418/car-app-card-host-lib/sample-host/). Shows all available AppCards in the system, along with\n testing capabilities.\n\n - DriverUI and [Pano manager](https://cs.android.com/android/platform/superproject/+/android-latest-release:packages/services/Car/car_product/distant_display/apps/CarDistantDisplayPanoManager/;l=1?q=CarDistantDisplayPanoManager&sq=&ss=android%2Fplatform%2Fsuperproject%2Fmain). Pano manager acts as the picker while\n DriverUI acts as the presenter.\n\n2. How many AppCards can each `AppCardContentProvider` support?\n\n An `AppCardContentProvider` can support an infinite number of AppCards.\n However, be sure to balance the number of AppCards with degraded performance\n versus a positive user experience."]]
