แนะนำแป้นพิมพ์ลัดโดยใช้ 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

    KotlinJava
    val shortcutsClient =
     
    AssistantShortcutSuggestionsClient.builder()
       
    .setContext(CONTEXT: Context)
       
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
       
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
       
    .build()
    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 ของทางลัดจะแสดง ที่ต้องการแนะนำให้กับผู้ใช้ ตัวอย่างต่อไปนี้ สร้างความตั้งใจให้ทางลัดเริ่มต้นการออกกำลังกาย

      KotlinJava
      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()
       
        Map
    2. ส่ง Intent ของทางลัดไปยังเมธอด lookupShortcut

      KotlinJava
      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
      }
      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 ที่คุณใช้เพื่อเริ่มกิจกรรมการแนะนำทางลัดในบริบทของแอป

      KotlinJava
      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))
        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"

      KotlinJava
      val exerciseShortcut = AppShortcutSuggestion.builder()
         
      .setAppShortcutIntent(appShortcutIntent)
         
      .setCommand("start a run")
         
      .build()
      AppShortcutSuggestion exerciseShortcut =
         
      AppShortcutSuggestion.builder()
             
      .setAppShortcutIntent(appShortcutIntent)
             
      .setCommand("start a run")
             
      .build();
    • createShortcutSettingsIntent: แสดงผล Intent ของ Android ที่นําผู้ใช้ไปยังอินเทอร์เฟซการตั้งค่าทางลัดในแอป Assistant

      KotlinJava
      val intent = shortcutsClient.createShortcutSettingsIntent().await()
      application
      .startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
        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

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

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