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

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

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

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

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีเพิ่มจำนวนกลุ่มเป้าหมายของแอปได้ที่ขยายแอปด้วย App Actions

In-App Promo SDK มีเมธอดต่อไปนี้

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

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

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

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

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

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

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

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

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

   • CUSTOM_EXECUTOR (ไม่บังคับ) เป็น 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 ของทางลัดไปยังเมธอด 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"

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

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

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

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

"GoogleInstallationUnsupportedException: Cannot bind to service"

เนื่องจากการกรองระดับการมองเห็นแพ็กเกจ ข้อผิดพลาด "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 โดยใช้อินเทอร์เฟซของแอปผู้ช่วย

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

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