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

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

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 ของทางลัดไปยังเมธอด 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 ที่แสดงในขั้นตอนก่อนหน้า

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

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

"GoogleINSTALL ไม่รองรับException: ไม่สามารถเชื่อมโยงกับบริการ"

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

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchb>ox&<quot; /
>  /quer<ies
  ...>
/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

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

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