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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• הרחבת האפליקציה ל-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. משתמשים ב-method‏ lookupShortcut כדי לקבוע אם קיצור הדרך שרוצים להציע תקף, ואם הוא כבר קיים.

   1. יצירת 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 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. יוצרים את ההצעה באמצעות מקש הקיצור 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".

     הערה: אל תכללו את Hey Google בהצעה.

     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 באמצעות הכוונה של Android שהוחזרה בשלב הקודם.

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

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

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

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

בעקבות סינון הרשאות גישה של חבילות, 'GoogleInstallationUnsupportedException: אי אפשר לקשר לשירות' עשוי להתרחש Android מגרסה 11 ואילך. צריך לוודא שcom.google.android.googlequicksearchbox כלולה בתג <queries> במניפסט:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

"Failed to verify the APK signature"

השגיאה הבאה עשויה להתרחש אם לא שולחים את אפליקציית הייצור בתור 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.

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

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