แนะนำแป้นพิมพ์ลัดโดยใช้ 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 ของทางลัดจะแสดง ที่ต้องการแนะนำให้กับผู้ใช้ ตัวอย่างต่อไปนี้ สร้างความตั้งใจให้ทางลัดเริ่มต้นการออกกำลังกาย

      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. ส่ง 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 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 เริ่มวิ่ง" เป็นทางลัด แทนที่ 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: ไม่สามารถเชื่อมโยงกับบริการ"

เนื่องจาก การกรองระดับการเข้าถึงแพ็กเกจ "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

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

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