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

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

דרישות לגבי מכשירים

כדי לבדוק את ההצעות במכשיר, צריך להתקין בו את האפליקציות הבאות:

מגבלות ידועות

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

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

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

    1. יוצרים 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();
       
    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 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);
          );
  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.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.

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

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