แนะนำแป้นพิมพ์ลัดโดยใช้ SDK การโปรโมตในแอป

หากต้องการโปรโมตฟีเจอร์ของแอปและทำให้ใช้งานง่ายขึ้น คุณอาจแนะนำ ทางลัด Assistant สำหรับผู้ใช้ของคุณ ทางลัดของ Assistant เป็นวลีสั้นๆ ที่ ผู้ใช้สามารถพูดเพื่อทริกเกอร์ฟังก์ชันการทำงานภายในแอปของคุณได้

แม้ว่าผู้ใช้จะสร้างทางลัดของ Assistant ด้วยตนเองได้ แต่ SDK การโปรโมตในแอปช่วยให้คุณแนะนําและใช้ Assistant ในเชิงรุกได้ ทางลัด การแนะนำทางลัดจะทำให้ผู้ใช้ของคุณทราบได้อย่างชัดเจนและเรียบง่าย กลับไปยังกิจกรรมโปรดของพวกเขาในแอปได้โดยที่คุณไม่ต้องทำอะไรเพิ่มเติม ในการตั้งค่าแป้นพิมพ์ลัด

เช่น หากผู้ใช้ค้นหา "การออกกำลังกายด้วยเฮฟวี่เมทัล" ในเพลงของคุณ คุณอาจแนะนำทางลัดของ Assistant ไปยังผลการค้นหาเหล่านั้นโดยตรง ในอนาคต เมื่อคุณแนะนำทางลัด ระบบจะแสดงข้อความแจ้งในแอปว่า แสดงวลีที่เสนอสำหรับทางลัดนั้น และถามผู้ใช้ว่าทางลัดนั้นหรือไม่ สามารถสร้างได้

ในตัวอย่างนี้ คุณแนะนำวลี "เริ่มเล่นเฮฟวี่เมทัลของฉัน ออกกำลังกาย" ผู้ใช้ยอมรับคำแนะนำและสามารถเรียกใช้ทางลัดได้โดย พูดว่า "Ok Google เริ่มออกกำลังกายเฮฟวี่เมทัล"

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีเพิ่มจำนวนผู้ชมของแอป โปรดดู พัฒนาแอปให้เติบโตด้วยการดำเนินการในแอป

SDK การโปรโมตในแอปมีเมธอดต่อไปนี้

• lookupShortcut: ตรวจสอบว่ามีทางลัดที่คุณต้องการแนะนำหรือไม่ มีอยู่ เมธอดนี้จะตรวจหาปัญหาที่ทำให้ทางลัดไม่ได้ด้วย ให้สร้างขึ้น หากสร้างทางลัดไม่ได้ lookupShortcut จะแสดงเหตุผล

• createShortcutSuggestionIntent: แสดง Intent ที่คุณใช้เพื่อ แจ้งให้ผู้ใช้สร้างทางลัดที่แนะนำ

• createShortcutSettingsIntent: แสดง Intent ที่ใช้ย้ายได้ ให้ผู้ใช้ไปที่การตั้งค่าทางลัดของ Assistant สำหรับแอปของคุณ

ข้อกำหนดเบื้องต้นและข้อจำกัด

ส่วนนี้จะอธิบายข้อกำหนดเบื้องต้นและข้อกำหนดในการใช้คำแนะนำ รวมถึงข้อจำกัดที่คุณอาจพบ

ข้อกำหนดเบื้องต้นสำหรับการพัฒนา

สภาพแวดล้อมในการพัฒนาซอฟต์แวร์ต้องเป็นไปตามข้อกำหนดต่อไปนี้จึงจะใช้คำแนะนำได้ ของ Google

• ขยายแอป Android เป็น ใช้การดำเนินการของแอป

• รวม com.google.android.googlequicksearchbox ภายใน <queries> ในไฟล์ Manifest เช่น

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

• ใช้ Android App Bundle เพื่อเผยแพร่แอป

ข้อกำหนดของอุปกรณ์

ในการทดสอบคำแนะนำในอุปกรณ์ อุปกรณ์ของคุณต้องมีสิ่งต่อไปนี้ ติดตั้งไว้แล้ว

• เวอร์ชันล่าสุดของ แอป Google

• Android 6.0 (API ระดับ 23) ขึ้นไป

ข้อจำกัดที่ทราบ

คำแนะนำมีเป็นภาษาอังกฤษเท่านั้น หากต้องการให้ผู้ใช้เห็นคำแนะนำของคุณ บุตรหลานต้องตั้งค่าภาษาของ Assistant ในอุปกรณ์เป็นภาษาอังกฤษ

ใช้คำแนะนำ

หากต้องการใช้คำแนะนำ คุณต้องอัปเดต build.gradle ให้ตั้งค่าไคลเอ็นต์การแนะนำ แล้วกำหนดคำแนะนำที่คุณ ที่ต้องการมอบให้แก่ผู้ใช้

1. เพิ่มทรัพยากร Dependency ของไลบรารีลงในไฟล์ 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 Intent สร้างโดย AssistantShortcutSuggestionsClient ได้รับการยืนยันแล้ว ถ้า Intent ไม่ถูกต้อง ระบบจะแสดงผลข้อยกเว้น

   • CUSTOM_EXECUTOR (ไม่บังคับ) เป็นผู้ดำเนินการที่กำหนดเองสำหรับการเรียกใช้ งานที่ไม่พร้อมกัน หากไม่ได้ระบุไว้ SDK จะใช้ ผู้ดำเนินการแบบแยกชุดข้อความเดียวสำหรับงาน

3. ใช้เมธอด lookupShortcut เพื่อระบุว่าทางลัดที่คุณต้องการหรือไม่ แนะนำเป็น URL ที่ถูกต้อง และไม่บังคับว่ามีทางลัดอยู่แล้วหรือไม่

   1. สร้าง Intent ทางลัดของแอป 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 ของทางลัดไปยังเมธอด 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 ของทางลัด มี 2 วิธีที่คุณ สามารถใช้เพื่อสร้างคำแนะนำได้:

   • 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 สั่งชาไข่มุก" เป็นทางลัด แทนที่ 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 โดยใช้ Intent ของ Android ที่แสดงในขั้นตอนก่อนหน้า

แก้ปัญหาคำแนะนำ

ส่วนนี้จะแสดงปัญหาและข้อยกเว้นที่คุณอาจพบเมื่อแนะนำทางลัด

"Googleติดตั้งส่วนขยายที่ไม่สนับสนุน: ไม่สามารถเชื่อมโยงกับบริการ"

เนื่องจาก การกรองระดับการเข้าถึงแพ็กเกจ "GoogleInstallationUnsupportedException: เชื่อมโยงกับบริการไม่ได้" อาจเกิดขึ้นในวันที่ Android 11 ขึ้นไป โปรดตรวจสอบว่า com.google.android.googlequicksearchbox รวมอยู่ในแท็ก <queries> ในไฟล์ Manifest ของคุณ:

<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

กิจกรรมการสร้างทางลัดจะปิดทันทีโดยไม่แสดงเนื้อหาใดๆ

กิจกรรมการสร้างทางลัดสามารถปิดได้โดยไม่ต้องแสดงเนื้อหาหากคุณ ไม่สร้างตัวอย่างโดยใช้เครื่องมือทดสอบการดำเนินการของแอป หรือหากตัวอย่าง หมดอายุ โปรดอัปเดตตัวอย่างแล้วลองอีกครั้ง