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

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

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

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

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

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

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

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

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

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

דרישות מוקדמות ומגבלות

בקטע הזה מתוארות הדרישות המוקדמות והדרישות לשימוש בהצעות, וגם המגבלות שעשויות לצוץ.

דרישות מוקדמות לפיתוח

כדי להשתמש בהצעות, סביבת הפיתוח חייבת לעמוד בדרישות הבאות בדרישות המוקדמות.

• הרחבת האפליקציה ל-Android כדי להשתמש בפעולות באפליקציה.

• יש לכלול com.google.android.googlequicksearchbox בתוך <queries> במניפסט. לדוגמה:

  <manifest ...>
    <queries>
      <package android:name="com.google.android.googlequicksearchb>ox&<quot; /
  >  /quer<ies
    ...>
  /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 (חובה) קובע אם לאמת כל כוונה שנוצרת כשמציעים קיצורי דרך למשתמשים. כשהערך הוא true, ה-Intents שנוצרו על ידי AssistantShortcutSuggestionsClient, מאומתים. אם ה-Intent לא תקין, תוחזר החרגה.

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

3. משתמשים ב-method‏ lookupShortcut כדי לקבוע אם קיצור הדרך שרוצים להציע תקף, ואם הוא כבר קיים.

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

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

   2. מעבירים את הכוונה של קיצור הדרך לשיטה 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. יוצרים את ההצעה באמצעות כוונת הקיצור. יש שתי שיטות יכולים לשמש ליצירת הצעה:

   • 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: מחזירה 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 באמצעות כוונת ה-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.googlequicksearchb>ox&<quot; /
>  /quer<ies
  ...>
/manifest

"האימות של חתימת ה-APK נכשל"

השגיאה הבאה עשויה להתרחש אם לא שולחים את האפליקציה בסביבת הייצור בתור חבילת אפליקציות:

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.

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

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