הצעת קיצורי דרך באמצעות ה-SDK של קידום מכירות בתוך האפליקציה

כדי לקדם תכונות של האפליקציה ולהקל את השימוש בה, אפשר להציע קיצורי הדרך של Assistant למשתמשים. קיצורי הדרך של Assistant הם משפטים תמציתיים משתמש יכול להשמיע פונקציונליות בתוך האפליקציה שלכם.

למרות שהמשתמשים יכולים ליצור קיצורי דרך ל-Assistant באופן ידני, בעזרת ה-SDK של קידום מכירות בתוך האפליקציה, אפשר להציע ולהטמיע את Assistant באופן יזום על ידי הצעות לקיצורי דרך, אתם מספקים למשתמשים גישה ברורה ופשוטה חוזרים לפעילויות האהובות עליהם באפליקציה בלי מאמץ נוסף בהגדרת קיצורי הדרך.

לדוגמה, אם משתמש מבצע חיפוש של 'אימון מטאלי'. במוזיקה אפשר להציע קיצור דרך ל-Assistant ישירות לתוצאות החיפוש האלה הוא בעתיד. כשמציעים קיצור דרך, מופיעה באפליקציה הנחיה מציג את הביטוי המוצע לקיצור הדרך ושואל את המשתמש אם קיצור הדרך .

בדוגמה הזו, אתם מציעים את הביטוי "תפעילו את הבי מטאל שלי" אימון". המשתמש מקבל את ההצעה ואז יכול להפעיל את קיצור הדרך באמצעות כשאומרים, "Ok Google, start my heavy Metal train".

למידע נוסף על דרכים להגדלת קהל המשתמשים של האפליקציה שלך: מרחיבים את הפעילות של האפליקציה בעזרת פעולות באפליקציה.

ה-SDK של קידום מכירות בתוך האפליקציה מספק את השיטות הבאות:

• 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 להגדיר את לקוח ההצעות, ואז להגדיר את ההצעות שרוצים לתת למשתמשים.

1. צריך להוסיף את התלות של הספרייה לקובץ build.gradle.

   dependencies {
     ...
     implementation "com.google.assistant.appactions:suggestions:1.0.0"
   }
   

2. מגדירים מופע של 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, ה-Intents שנוצרו על ידי AssistantShortcutSuggestionsClient, מאומתות. אם המיקום Intent לא חוקי, מוחזר חריג.

   • CUSTOM_EXECUTOR (אופציונלי) הוא קובץ הפעלה מותאם אישית להרצה ומשימות אסינכרוניות. אם לא תספקו אותו, ערכת ה-SDK משתמשת הגורם האחראי למשימה בשרשור יחיד.

3. משתמשים בשיטה lookupShortcut כדי לקבוע אם מקש הקיצור שרוצים מציע תקין, ואם כן, אם קיצור הדרך כבר קיים.

   1. יצירת Intent לקיצור דרך לאפליקציה. קיצור הדרך מייצג את מקש הקיצור שרוצים להציע למשתמש. הדוגמה הבאה יוצרת Intent לקיצור דרך להזמנת משקה.

      Kotlin

      val menuItem = mapOf(
          "@type" to "MenuItem",
          "@context" to "http://schema.googleapis.com",
          "name" to "Fresh Lemon Honey Jasmine Green Tea",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build()
       

      Java

        Map<String, Object> menuItem = new HashMap<>();
        menuItem.put("@type", "MenuItem");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.ORDER_MENU_ITEM")
                .setPackageName("my.app.package")
                .setIntentParamName("menuItem")
                .setIntentParamValue(menuItem)
                .build();
       

   2. מעבירים את ה-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));
      

4. יוצרים את ההצעה באמצעות מקש הקיצור Intent. יש שתי שיטות יכולים לשמש ליצירת הצעה:

   • createShortcutSuggestionIntent: מחזירה Intent של Android להשתמש בו כדי להתחיל את הפעילות של ההצעות לקיצורי הדרך בהקשר של אפליקציה.

     Kotlin

     val orderShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand(PHRASE: String)
         .build()
     
     val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
     application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
     

     Java

       AppShortcutSuggestion orderShortcut =
           AppShortcutSuggestion.builder()
               .setAppShortcutIntent(appShortcutIntent)
               .setCommand(PHRASE: String)
               .build();
     
       shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
           .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, order my Barrow Te" כקיצור דרך, להחליף PHRASE עם "order my bubble tea".

     Kotlin

     val orderShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand("order my bubble tea")
         .build()
     

     Java

     AppShortcutSuggestion orderShortcut =
         AppShortcutSuggestion.builder()
             .setAppShortcutIntent(appShortcutIntent)
             .setCommand("order my bubble tea")
             .build();
     

   • createShortcutSettingsIntent: מחזירה Intent של Android שפועל למשתמש לממשק ההגדרות של קיצורי הדרך באפליקציית Assistant.

     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);
         );
     

5. התקשרות אל startActivity באמצעות כוונת הרכישה ב-Android שהוחזרה בשלב הקודם.

פתרון בעיות בהצעות

בקטע הזה מפורטות בעיות וחריגים שאתם עשויים להיתקל בהם כשמציעים קיצורי דרך.

"GoogleInstallation_supported פירושו: לא ניתן לקשר לשירות"

בעקבות סינון הרשאות גישה של חבילות, 'GoogleInstallationUnsupportedException: אי אפשר לקשר לשירות' עשוי להתרחש 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.

פעילות של יצירת קיצורי דרך נסגרת באופן מיידי בלי להציג תוכן

הפעילות של יצירת קיצור דרך עשויה להיסגר מבלי להציג תוכן אם אין ליצור תצוגה מקדימה באמצעות כלי הבדיקה של 'פעולות באפליקציה' או אם התצוגה המקדימה בתוקף עד. צריך לעדכן את התצוגה המקדימה ולנסות שוב.