כדי לקדם תכונות באפליקציה ולהקל על השימוש בה, אתם יכולים להציע למשתמשים קיצורי דרך לפעולה של Assistant. קיצורי דרך לפעולות של Assistant הם ביטויים קצרים שהמשתמשים יכולים לומר כדי להפעיל פונקציונליות באפליקציה.
המשתמשים יכולים ליצור קיצורי דרך ל-Assistant באופן ידני, אבל In-App Promo SDK מאפשר לכם להציע ולהטמיע קיצורי דרך ל-Assistant באופן יזום. הצעת קיצורי דרך מספקת למשתמשים דרכים ברורות ופשוטות לחזור לפעילויות המועדפות עליהם באפליקציה, בלי המאמץ הנוסף של הגדרת קיצורי הדרך.
לדוגמה, אם משתמש מחפש "אימון עם מוזיקת מטאל" באפליקציית המוזיקה שלכם, אתם יכולים להציע קיצור דרך לפעולה של Assistant שיוביל ישירות לתוצאות החיפוש האלה בעתיד. כשמציעים קיצור דרך, מופיעה באפליקציה הנחיה עם הביטוי המוצע לקיצור הדרך, והמשתמש נשאל אם אפשר ליצור את קיצור הדרך.
בדוגמה הזו, אתם מציעים את הביטוי "start my heavy metal workout". המשתמש מקבל את ההצעה ויכול להפעיל את קיצור הדרך באמירת "Ok Google, start my heavy metal workout".
במאמר הרחבת קהל המשתמשים באפליקציה באמצעות פעולות באפליקציה מוסבר איך להגדיל את קהל המשתמשים באפליקציה.
ה-SDK של קידום מכירות באפליקציה מספק את ה-methods הבאות:
lookupShortcut: בודק אם קיצור הדרך שאתם רוצים להציע כבר קיים. השיטה גם בודקת אם יש בעיות שמונעות את יצירת קיצור הדרך. אם אי אפשר ליצור את קיצור הדרך, הפונקציהlookupShortcutמחזירה את הסיבות לכך.
createShortcutSuggestionIntent: מחזירה Intent שאפשר להשתמש בו כדי לבקש מהמשתמש ליצור את קיצור הדרך המוצע.
createShortcutSettingsIntent: מחזירה Intent שאפשר להשתמש בו כדי להעביר את המשתמש להגדרות של קיצור הדרך לפעולה של Assistant באפליקציה.
דרישות מוקדמות ומגבלות
בקטע הזה מתוארות הדרישות המוקדמות והדרישות לשימוש בהצעות, וגם המגבלות שאתם עשויים להיתקל בהן.
דרישות מוקדמות לפיתוח
כדי להשתמש בהצעות, סביבת הפיתוח שלכם צריכה לעמוד בדרישות המוקדמות הבאות.
להרחיב את אפליקציית Android כדי להשתמש בפעולות באפליקציה.
צריך לכלול את
com.google.android.googlequicksearchboxבתג<queries>במניפסט. לדוגמה:<manifest ...> <queries> <package android:name="com.google.android.googlequicksearchbox" /> </queries> ... </manifest>משתמשים ב-קובצי Android App Bundle כדי לפרסם את האפליקציות.
דרישות לגבי מכשירים
כדי לבדוק את ההצעות במכשיר, צריך להתקין בו את האפליקציות הבאות:
הגרסה העדכנית של אפליקציית Google
Android מגרסה 6.0 (רמת API 23) ומעלה
מגבלות ידועות
ההצעות נתמכות רק באנגלית. כדי שהמשתמשים יראו את ההצעות שלכם, הם צריכים להגדיר את השפה של Assistant במכשיר שלהם לאנגלית.
יישום ההצעות
כדי להטמיע הצעות, צריך לעדכן את הקובץ build.gradle, להגדיר את הלקוח של ההצעות ואז להגדיר את ההצעות שרוצים לתת למשתמשים.
מוסיפים את התלות של הפרויקט בספרייה לקובץ
build.gradle.dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }מגדירים מופע של
AssistantShortcutSuggestionsClient.Kotlin
val shortcutsClient = AssistantShortcutSuggestionsClient.builder() .setContext(CONTEXT: Context) .setVerifyIntents(VERIFY_INTENTS: Boolean) .setCustomExecutor(CUSTOM_EXECUTOR: Object) .build()
Java
AssistantShortcutSuggestionsClient shortcutsClient = AssistantShortcutSuggestionsClient.builder() .setContext(CONTEXT: Context) .setVerifyIntents(VERIFY_INTENTS: Boolean) .setCustomExecutor(CUSTOM_EXECUTOR: Object) .build();
בדוגמה הזו:
CONTEXT(חובה) הוא ההקשר של האפליקציה.VERIFY_INTENTS(חובה) קובע אם לאמת כל Intent שנוצר כשמציעים קיצורי דרך למשתמשים. כאשרtrue, ה-intent שנוצרו על ידיAssistantShortcutSuggestionsClientמאומתים. אם ה-Intent לא תקין, תוחזר חריגה.
CUSTOM_EXECUTOR(אופציונלי) הוא מפעיל מותאם אישית להרצת משימות אסינכרוניות. אם לא מספקים אותו, ה-SDK משתמש ב-executor עם שרשור יחיד למשימה.
אתם יכולים להשתמש ב-
lookupShortcutכדי לבדוק אם קיצור הדרך שאתם רוצים להציע תקין, ואם הוא כבר קיים.יוצרים Intent של קיצור דרך לאפליקציה. ה-intent של קיצור הדרך מייצג את קיצור הדרך שאתם רוצים להציע למשתמש. בדוגמה הבאה נוצר Intent לקיצור דרך כדי להתחיל אימון.
Kotlin
val exercise = mapOf( "@type" to "Exercise", "@context" to "http://schema.googleapis.com", "name" to "Running", ) val appShortcutIntent = AppShortcutIntent.builder() .setIntentName("actions.intent.START_EXERCISE") .setPackageName("my.app.package") .setIntentParamName("exercise") .setIntentParamValue(exercise) .build()
Java
Map<String, Object> exercise = new HashMap<>(); exercise.put("@type", "Exercise"); menuItem.put("@context", "http://schema.googleapis.com"); menuItem.put("name", "Running"); AppShortcutIntent appShortcutIntent = AppShortcutIntent.builder() .setIntentName("actions.intent.START_EXERCISE") .setPackageName("my.app.package") .setIntentParamName("exercise") .setIntentParamValue(exercise) .build();
מעבירים את ה-intent של קיצור הדרך ל-method
lookupShortcut.Kotlin
val result = shortcutsClient.lookupShortcut(appShortcutIntent).await() if (!result.isShortcutPresent) { // App can suggest creating a shortcut } else { // App can remind the user that they have a shortcut for this app action }
Java
shortcutsClient.lookupShortcut(appShortcutIntent) .addOnSuccessListener(shortcutLookupResult -> { if (!shortcutLookupResult.isShortcutPresent()) { // App can suggest creating a shortcut } else { // App can remind the user that they have a shortcut for this app action } }) .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));
יוצרים את ההצעה באמצעות ה-intent של קיצור הדרך. יש שתי שיטות ליצירת הצעה:
createShortcutSuggestionIntent: מחזירה Intent של Android שמשמש להפעלת הפעילות של הצעת קיצור הדרך בהקשר של האפליקציה.Kotlin
val exerciseShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand(PHRASE: String) .build() val intent = shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut).await() application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
Java
AppShortcutSuggestion exerciseShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand(PHRASE: String) .build(); shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut) .addOnSuccessListener(intent -> getApplication().startActivity( intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)); ) .addOnFailureListener(e -> Log.e(TAG, "Failed to get shortcut suggestion intent", e); );
בדוגמה הזו, PHRASE הוא הביטוי שרוצים להציע למשתמש כקיצור דרך. לדוגמה, אם אתם רוצים שהמשתמש יגיד "Ok Google, start a run" כקיצור דרך, החליפו את PHRASE ב-
"start a run".Kotlin
val exerciseShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("start a run") .build()
Java
AppShortcutSuggestion exerciseShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("start a run") .build();
createShortcutSettingsIntent: מחזירה Android Intent שמעבירה את המשתמש לממשק של הגדרות קיצורי הדרך באפליקציית עזרה.Kotlin
val intent = shortcutsClient.createShortcutSettingsIntent().await() application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
Java
shortcutsClient.createShortcutSettingsIntent() .addOnSuccessListener(intent -> getApplication().startActivity( intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)); ) .addOnFailureListener(e -> Log.e(TAG, "Failed to get shortcut settings intent", e); );
מפעילים את
startActivityבאמצעות ה-Intent של Android שהוחזר בשלב הקודם.
הצעות לפתרון בעיות
בקטע הזה מפורטות בעיות וחריגות שאתם עלולים להיתקל בהן כשאתם מציעים קיצורי דרך.
"GoogleInstallationUnsupportedException: Cannot bind to service"
בגלל סינון הרשאות הגישה לחבילות, יכול להיות שתופיע השגיאה "GoogleInstallationUnsupportedException: Cannot bind to service" ב-Android מגרסה 11 ואילך. חשוב לוודא שההרשאה com.google.android.googlequicksearchbox
כלולה בתג <queries> במניפסט:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchbox" />
</queries>
...
</manifest>
"אימות החתימה של ה-APK נכשל"
השגיאה הבאה יכולה להתרחש אם לא שולחים את האפליקציה בסביבת הייצור כ-App Bundle:
Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.
חשוב לוודא שהאפליקציה נשלחת כקובץ Android App Bundle.
"לא הצלחנו לקבל את קיצורי הדרך של המשתמש"
הודעת השגיאה "לא ניתן לאחזר את קיצורי הדרך של המשתמש" יכולה להופיע אם לאחרונה הוספתם חשבון למכשיר ונתוני קיצורי הדרך של החשבון החדש עדיין לא נשמרו במטמון של המכשיר.
כדי לסנכרן את נתוני קיצורי הדרך במכשיר, צריך להוסיף או למחוק קיצור דרך לפעולה של Assistant באמצעות הממשק של אפליקציית Assistant.
פעילות יצירת קיצור הדרך נסגרת מיד בלי להציג תוכן כלשהו
הפעילות ליצירת קיצור דרך יכולה להיסגר בלי להציג תוכן אם לא יוצרים תצוגה מקדימה באמצעות כלי הבדיקה של פעולות באפליקציה, או אם התצוגה המקדימה פגה. צריך לעדכן את התצוגה המקדימה ולנסות שוב.