สร้างทางลัด.xml

เมื่อระบุฟังก์ชันการทำงานในแอปและ Intent ในตัวที่เกี่ยวข้อง (BII) เพื่อนำไปใช้งานแล้ว ให้ประกาศ BII ที่ฟังก์ชันการทำงานรองรับโดยกำหนดองค์ประกอบ capability ในไฟล์ทรัพยากร shortcuts.xml การประกาศ BII เป็น capability จะลงทะเบียนการรองรับความตั้งใจเชิงความหมายนั้นในแอป และเปิดใช้การตอบสนองคำค้นหาด้วยเสียงตามความตั้งใจโดยใช้ Google Assistant

Assistant ใช้การประมวลผลภาษาธรรมชาติเพื่อดึงข้อมูลพารามิเตอร์จากการค้นหาของผู้ใช้ ข้อมูลอ้างอิงเกี่ยวกับ Intent ในตัวจะแสดงรายการช่องที่ BII แต่ละรายการดึงข้อมูลจากคำค้นหาของผู้ใช้ที่เกี่ยวข้องได้ ตัวอย่างเช่น หากผู้ใช้เรียกใช้ความสามารถ [actions.intent.GET_FOOD_OBSERVATION][] ในแอปโดยพูดว่า "Ok Google ขอให้ ExampleApp บอกฉันว่าฉันกินอะไรเป็นอาหารกลางวันวันศุกร์ที่ผ่านมา" Assistant จะดึงข้อมูลพารามิเตอร์ BII ต่อไปนี้จากคําขอของผู้ใช้

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

Assistant จะส่งพารามิเตอร์ BII ไปยัง intent การดำเนินการตามคำสั่งซื้อที่กําหนดไว้ใน capability คุณกำหนดเอลิเมนต์ intent อย่างน้อย 1 รายการในความสามารถเพื่อรองรับวิธีที่ผู้ใช้อาจเรียกใช้ BII ได้ เช่น คุณอาจกําหนด Fulfillment intent ที่จําเป็นต้องใช้ทั้งพารามิเตอร์ BII ในตัวอย่างนี้ จากนั้นคุณอาจกำหนด Intent รายการที่ 2 ซึ่งต้องใช้พารามิเตอร์ BII รายการเดียว foodObservation.forMeal ซึ่งจะรายงานสำหรับอาหารทุกมื้อในวันหนึ่งๆ เช่น "Ok Google ขอให้ ExampleApp บอกฉันว่าฉันกินอะไรเป็นอาหารกลางวัน"

หมายเหตุ: capability สำรองแต่ละรายการต้องมีพารามิเตอร์ที่ไม่จำเป็นต้องมีเพื่อตอบสนองคำขอของผู้ใช้intent Intent สำรองเหล่านี้จะช่วยปรับปรุงประสบการณ์ของผู้ใช้ด้วยการอนุญาตให้ดำเนินการสําเร็จได้แม้จะเป็นคําค้นหาที่คลุมเครือของผู้ใช้ เช่น "Ok Google ขอให้ ExampleApp ถามฉันว่าฉันกินอะไร"

ภาพรวม

คุณกำหนดค่าการดำเนินการของแอปโดยใช้ไฟล์ shortcuts.xml ที่วางไว้ในไดเรกทอรี res/xml ของโปรเจ็กต์แอป จากนั้นสร้างการอ้างอิงถึง shortcuts.xml ในไฟล์ Manifest ของแอป เพิ่มการอ้างอิง shortcuts.xml ในไฟล์ Manifest ของแอปโดยทำตามขั้นตอนต่อไปนี้

1. ในไฟล์ Manifest ของแอป (AndroidManifest.xml) ให้ค้นหากิจกรรมที่มีการตั้งค่าตัวกรอง Intent เป็นการดำเนินการ android.intent.action.MAIN และหมวดหมู่ android.intent.category.LAUNCHER

2. เพิ่มการอ้างอิงถึง shortcuts.xml ใน AndroidManifest.xml โดยใช้แท็ก <meta-data> ใน Activity ที่มีตัวกรอง Intent ทั้งสําหรับ MAIN และ LAUNCHER ดังนี้

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

ตัวอย่างข้างต้นจะประกาศทรัพยากร XML สำหรับไฟล์ xml/shortcuts.xml ใน APK ดูรายละเอียดเพิ่มเติมเกี่ยวกับการกำหนดค่าทางลัดได้ที่หัวข้อสร้างทางลัดแบบคงที่ในเอกสารประกอบสำหรับนักพัฒนาแอป Android

หมายเหตุ: หากคุณใช้เครื่องมือสร้างความสับสนสำหรับ APK รุ่น ให้ปิดใช้ความสับสนสำหรับไฟล์ shortcuts.xml ของแอปโดยใช้รายการที่อนุญาต หากไม่ดำเนินการดังกล่าว คุณอาจพบข้อผิดพลาดเมื่ออัปโหลด APK ไปยัง Google Play Console

ต้องใช้คลัง Jetpack androidx.core:core:1.6.0 (หรือเวอร์ชันที่ใหม่กว่า) ในโปรเจ็กต์ Android เพื่อหลีกเลี่ยงข้อผิดพลาดในการคอมไพล์เมื่อกำหนดความสามารถของ App Actions ใน shortcuts.xml โปรดดูรายละเอียดที่หัวข้อเริ่มต้นใช้งาน Android Jetpack

แป้นพิมพ์ลัดแบบคงที่

เมื่อกําหนด capability คุณสามารถประกาศองค์ประกอบ shortcut แบบคงที่ใน shortcuts.xml เพื่อขยายฟังก์ชันการทํางานของความสามารถ Assistant จะนำเข้าทางลัดแบบคงที่เมื่อคุณอัปโหลดรุ่นไปยัง Google Play Console เนื่องจากทางลัดแบบคงที่สามารถสร้างและอัปเดตได้โดยการเผยแพร่เวอร์ชันใหม่เท่านั้น ทางลัดจึงมีประโยชน์มากที่สุดในการไฮไลต์กิจกรรมและเนื้อหาทั่วไปในแอป

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

คุณเปิดใช้ฟังก์ชันการทำงานของแอปต่อไปนี้ได้ด้วยทางลัดแบบคงที่

• แป้นพิมพ์ลัดของความสามารถ สร้างทางลัดที่เปิดอินสแตนซ์ของ capability ที่มีค่าพารามิเตอร์ intent ที่กำหนดไว้ล่วงหน้า เช่น คุณอาจประกาศทางลัดของแอป "เริ่มการวิ่ง" ซึ่งจะเรียกใช้ความสามารถ BII ของ START_EXERCISE ในแอปฟิตเนส

  ซึ่งจะมีแอตทริบิวต์ intent, shortLabel และ longLabel ทำให้มีสิทธิ์ได้รับการแนะนำและแสดงเป็นชิปในแพลตฟอร์มที่ทำงานแบบเชิงรุก เช่น Assistant หรือเมื่อกดไอคอนแอปบน Launcher ของ Android ค้างไว้ แป้นพิมพ์ลัดของการดำเนินการยังใช้เป็นแป้นพิมพ์ลัดของเอนทิตีได้ด้วย โดยรายละเอียดมีดังนี้ ให้เชื่อมโยงแป้นพิมพ์ลัดกับ capability โดยใช้แท็ก <capability-binding>

• แป้นพิมพ์ลัดสำหรับเอนทิตี ทางลัดเอนทิตีแสดงรายการค่าพารามิเตอร์ที่รองรับสำหรับการตอบสนองการค้นหาด้วยเสียงของ capability เช่น ทางลัดเอนทิตีที่มีรายการประเภทการออกกำลังกาย ("เดินป่า" "วิ่ง" ฯลฯ) ซึ่งเชื่อมโยงกับพารามิเตอร์ exercise.name BII ของความสามารถ START_EXERCISE หากคำพูดของผู้ใช้ตรงกับเอนทิตี ระบบจะส่งรหัส shortcutId ไปยัง Intent แทนค่าการค้นหาของผู้ใช้แบบดิบ

  ทางลัด Entity ไม่ได้กำหนดแอตทริบิวต์ intent, shortLabel หรือ longLabel และด้วยเหตุนี้จึงไม่แนะนำในแพลตฟอร์มที่แสดงต่อผู้ใช้ โปรดดูรายละเอียดที่พื้นที่โฆษณาในบรรทัดสําหรับการกระทําในแอป

  หมายเหตุ: LauncherApps API จะทิ้งทางลัดแบบคงที่ที่ประกาศเป็นทางลัดเอนทิตี ซึ่งหมายความว่าทางลัดดังกล่าวจะใช้ได้กับ Launcher ของ Android

สคีมาความสามารถ

ตารางต่อไปนี้อธิบายสคีมาการดําเนินการของแอปสําหรับองค์ประกอบ capability ใน shortcuts.xml เมื่อใส่แท็ก จะต้องระบุแอตทริบิวต์ทั้งหมดของแท็กนั้น เว้นแต่จะระบุว่า "ไม่บังคับ"

แท็ก Shortcuts.xml	อยู่ใน	แอตทริบิวต์
<capability>	<shortcuts>	android:name app:queryPatterns (ใช้ได้กับความตั้งใจที่กําหนดเองเท่านั้น)
<intent>	<capability>	android:action (ไม่บังคับ) android:targetClass (ไม่บังคับ) android:targetPackage (ไม่บังคับ) android:data (ไม่บังคับ)
<url-template>	<intent>	android:value
<extra>	<intent>	android:key android:value ใช้ได้กับการเรียกใช้แอปที่ทำงานอยู่เบื้องหน้าเท่านั้น
<parameter>	<intent>	android:name android:key android:mimeType (ใช้ได้กับความตั้งใจที่กําหนดเองเท่านั้น) android:required (ไม่บังคับ) app:shortcutMatchRequired (ไม่บังคับ)
<shortcut-fulfillment>	<capability>	ใช้ได้กับพื้นที่โฆษณาในบรรทัดเท่านั้น
<parameter>	<shortcut-fulfillment>	android:name
<slice>	<capability>	ใช้ได้กับ Android Slice เท่านั้น

คำอธิบายสคีมาความสามารถ

ส่วนนี้จะอธิบายองค์ประกอบสคีมา capability

<capability>

capability ที่กําหนด Intent การดําเนินการของแอปที่แอปของคุณรองรับ องค์ประกอบ <capability> แต่ละรายการในไฟล์ shortcuts.xml ต้องมี <intent> อย่างน้อย 1 รายการเพื่อจัดการการดำเนินการ

แอตทริบิวต์:

• android:name: รหัสการดำเนินการของ Intent ในตัว (เช่น [actions.intent.GET_FOOD_OBSERVATION][]) ดูรายการ Intent ในตัวที่รองรับได้ที่ข้อมูลอ้างอิง Intent ในตัว
• app:queryPatterns: ทรัพยากรอาร์เรย์สตริงของคําค้นหาที่คาดหวังจากผู้ใช้สำหรับความตั้งใจนี้ แอตทริบิวต์นี้ใช้ได้กับIntent ที่กําหนดเองเท่านั้น เนื่องจาก BII มีรูปแบบของวิธีที่ผู้ใช้แสดงงานที่ต้องการทําหรือข้อมูลที่กําลังมองหาอยู่แล้ว

หมายเหตุ: Intent ในตัวของแอปการกระทําแตกต่างจาก Intent ของ Android BIIs จำลองการค้นหาของผู้ใช้สำหรับงานที่ผู้ใช้ต้องการดำเนินการในแอป ส่วน Intent ของ Android จะเปิดปลายทางในแอปของคุณโดยมีบริบทที่รวมอยู่ด้วย คุณประกาศแท็ก capability เพื่อจับคู่ BII กับ Intent ของ Android ที่เกี่ยวข้อง ซึ่งช่วยให้ผู้ใช้เปิดฟังก์ชันการทำงานในแอปได้โดยเรียกใช้ BII ด้วย Assistant

<intent>

องค์ประกอบ intent ของ Android ที่กําหนดวิธีตอบสนองคําค้นหาของผู้ใช้โดยใช้ฟังก์ชันการทํางานในแอป นักพัฒนาซอฟต์แวร์อาจระบุ<intent> แท็กหลายรายการในcapability Assistant จะพยายามดำเนินการตามคำค้นหาของผู้ใช้โดยใช้ <intent> รายการแรกใน capability ที่มีพารามิเตอร์ที่จำเป็นทั้งหมด

แอตทริบิวต์:

• android:action: ประเภท Intent Action ค่าเริ่มต้นคือ ACTION_VIEW
• android:targetClass: คลาสกิจกรรมเป้าหมาย เช่น "com.example.exercise.ExerciseActivity"
• android:targetPackage: แพ็กเกจที่มีคลาสกิจกรรมเป้าหมาย เช่น "com.example.exercise
• android:data: <url-template> จะเขียนทับฟิลด์นี้หากมีการประกาศแท็กนั้นใน intent

หมายเหตุ: android:targetClass และ android:targetPackage ต้องใช้กับ Intent ที่กําหนดเป้าหมายเป็นกิจกรรมอย่างชัดเจน นอกจากนี้ คุณยังใช้แอตทริบิวต์ android:data เพื่อกําหนดกิจกรรมเป้าหมายได้ด้วย โปรดดูรายละเอียดที่หัวข้อตัวเลือกการดำเนินการตาม Intent

<url-template>

เทมเพลตสำหรับสร้าง URI ของ Deep Link เพื่อเปิดในอุปกรณ์ ระบบอาจขยายเทมเพลตด้วยพารามิเตอร์ Intent ในตัว หากมีพารามิเตอร์ที่จําเป็นสําหรับเทมเพลตทั้งหมด ดูตัวอย่างเทมเพลต URL ของ HTTP ได้ที่บทความใน Wikipedia เกี่ยวกับเทมเพลต URL รูปแบบเทมเพลตเป็นไปตามข้อกำหนดเฉพาะเทมเพลต URI ของ RFC6570

ตัวอย่างค่าเทมเพลต URL มีดังนี้

เทมเพลต	ค่า	ค่าแบบขยาย
https://example.com/test{?foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo}	"foo": "123"	https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo}	"foo": "123"	myapp://example/123

ดูข้อมูลเพิ่มเติมเกี่ยวกับการกําหนดค่าเทมเพลต URL ได้ที่เทมเพลต URL ในการจำหน่าย

หมายเหตุ: <url-template> เป็นวิธีการที่ไม่บังคับสำหรับการกําหนดเป้าหมายกิจกรรมใน intent โปรดดูรายละเอียดที่หัวข้อตัวเลือกการดำเนินการตาม Intent

<extra>

กําหนดข้อมูลเพิ่มเติมสําหรับ intent สําหรับการดําเนินการของแอป ฟิลด์นี้ใช้เพื่อเปิดใช้ [การเรียกใช้แอปในเบื้องหน้า][] สําหรับ capability เท่านั้น

<parameter>

แมปพารามิเตอร์ BII กับค่าพารามิเตอร์ Intent ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลพารามิเตอร์และการจับคู่

แอตทริบิวต์:

• android:name: ชื่อพารามิเตอร์ BII ที่จะเชื่อมโยงกับพารามิเตอร์ intent นี้ ชื่อควรเป็นช่องระดับใบของพารามิเตอร์ BII (เช่น foodObservation.aboutFood.name)
• android:key: คีย์ที่นักพัฒนาแอปกำหนดสำหรับค่าพารามิเตอร์ BII เช่น คุณอาจกำหนด contact_name สำหรับพารามิเตอร์ BII message.recipient.name
• android:mimeType: mimeType ของพารามิเตอร์ เช่น text/* ต้องระบุช่องนี้สำหรับพารามิเตอร์ของIntent ที่กําหนดเองเท่านั้น
• android:required: ประกาศว่าข้อความค้นหาของผู้ใช้ต้องระบุพารามิเตอร์นี้หรือไม่เพื่อให้ระบบใช้ความตั้งใจนี้เพื่อการดำเนินการ หากไม่มีพารามิเตอร์นี้ Assistant จะพยายามดำเนินการตามคำค้นหาของผู้ใช้โดยใช้ intent รายการถัดไปที่กําหนดไว้สําหรับ capability

<shortcut-fulfillment>

ระบุว่าให้ใช้ intent ที่กําหนดไว้ในทางลัดพื้นที่โฆษณาในบรรทัดสําหรับพารามิเตอร์ที่ระบุเพื่อการดำเนินการตามคำสั่งซื้อ โปรดดูรายละเอียดที่หัวข้อการดำเนินการโดยใช้ Intent ทางลัด

<parameter> (สำหรับ <shortcut-fulfillment>)

แอตทริบิวต์ที่ไม่บังคับซึ่งแมปพารามิเตอร์ BII รายการเดียวกับการแสดงสินค้าคงคลังในบรรทัดเพื่อดำเนินการตามคำสั่งซื้อ โปรดดูรายละเอียดที่หัวข้อการดำเนินการโดยใช้ Intent ทางลัด

แอตทริบิวต์:

• android:name: ชื่อพารามิเตอร์ BII เพื่อเชื่อมโยงกับการแสดงโฆษณาในพื้นที่โฆษณาในบรรทัด การตอบสนองทางลัด ชื่อควรเป็นช่องระดับใบของพารามิเตอร์ BII (เช่น menuItem.name)

<slice>

ช่วยให้ Assistant สามารถฝังผลการค้นหาที่ตรงกับ capability นี้เป็นการแบ่งข้อมูล Android โปรดดูรายละเอียดที่หัวข้อผสานรวมการดำเนินการของแอปกับ Android Slice

สคีมาทางลัด

ตารางต่อไปนี้อธิบายแอตทริบิวต์ขององค์ประกอบ shortcut ที่ใช้เพื่อเปิดใช้ฟังก์ชันการทํางานของแอป เมื่อรวมแท็ก คุณต้องระบุแอตทริบิวต์ทั้งหมดของแท็ก เว้นแต่จะระบุว่า "ไม่บังคับ"

แท็ก Shortcuts.xml	อยู่ใน	แอตทริบิวต์
<shortcut>	<shortcuts>	android:shortcutId android:shortcutShortLabel android:shortcutLongLabel (ไม่บังคับ) android:icon (ไม่บังคับ)
<intent>	<shortcut>	android:action android:targetClass (ไม่บังคับ) android:targetPackage (ไม่บังคับ) android:data (ไม่บังคับ)
<capability-binding>	<shortcut>	android:key
<parameter-binding>	<capability-binding>	android:key (ไม่บังคับ) android:value
<extra>	<shortcut>	android:name (ไม่บังคับ) android:value ใช้ได้กับการจับคู่พารามิเตอร์ Enum เท่านั้น

คำอธิบายสคีมาทางลัด

ส่วนนี้จะอธิบายองค์ประกอบสคีมา shortcut

<shortcut>

<shortcut> ของ Android ที่กําหนดไว้ใน shortcuts.xml ซึ่งมีแอตทริบิวต์บางอย่างที่เกี่ยวข้องกับการกระทําของแอป ระบบจะอ้างอิงค่าสตริงสำหรับช่อง shortcutShortLabel และ shortcutLongLabel ผ่านทรัพยากรสตริงของ APK

แอตทริบิวต์:

• android:shortcutId: ตัวระบุสำหรับทางลัดนี้
• android:shortcutShortLabel: ทรัพยากรสตริงที่แสดงวลีทางลัดสั้นๆ เช่น "@string/callDavidShort" ที่แสดงค่า "โทรหา David"
• android:shortcutLongLabel: ทรัพยากรสตริงที่แสดงวลีทางลัดแบบยาว เช่น "@string/callDavidLong" ที่แสดงค่า "โทรเสียงหา David"

<intent>

Intent ของ Android ที่เชื่อมโยงกับทางลัดนี้ ระบบจะเรียกใช้ intent นี้เมื่อผู้ใช้เปิดทางลัดนี้โดยใช้เสียงหรือการแตะ

แอตทริบิวต์ Intent ของ shortcut จะเหมือนกับแอตทริบิวต์ capability intent

<capability-binding>

เชื่อมโยง shortcut กับ capability การดำเนินการของแอป การเพิ่มองค์ประกอบนี้ลงใน shortcut จะเปิดใช้การตอบสนองด้วยเสียงโดยใช้ Assistant

แอตทริบิวต์:

• android:key: แอตทริบิวต์ android:name ของ capability ที่ shortcut นี้เชื่อมโยงอยู่ เช่น actions.intent.START_EXERCISE

<parameter-binding>

แอตทริบิวต์ที่ไม่บังคับซึ่งเชื่อมโยง shortcut กับพารามิเตอร์เดียวของ App Action capability หากมีการกําหนด parameter-binding สําหรับ shortcut คุณจะใช้ทางลัดเพื่อระบุเอนทิตีสินค้าคงคลังในบรรทัดให้กับพารามิเตอร์ BII ได้ โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อพื้นที่โฆษณาในบรรทัดสําหรับ App Actions

แอตทริบิวต์:

• android:key: ชื่อพารามิเตอร์ BII capability ที่จะเชื่อมโยงกับทางลัดนี้ เช่น exercise.name
• android:value: ค่า entity ซึ่งอาจเป็น entity รายการเดียวหรือรายการแหล่งข้อมูลก็ได้

<extra>

extra แพ็กเกจข้อมูลสำหรับทางลัด sameAs เป็นข้อมูลเดียวที่เกี่ยวข้องกับองค์ประกอบ shortcut ของ App Actions URL sameAs หมายถึงหน้าเว็บอ้างอิงที่ระบุเอนทิตีอย่างชัดเจน ใช้เพื่อระบุค่า Enum เฉพาะในกรณีที่ประเภทพารามิเตอร์ Intent เป็นประเภทย่อยของ schema.org/Enumeration ฟิลด์พารามิเตอร์ต้องใช้ค่านี้หากประเภทเป็นประเภทย่อยของ schema.org/Enumeration (เช่น MealTypeBreakfast)

แอตทริบิวต์:

• android:key: ค่าที่รองรับสําหรับการดําเนินการของแอปคือ sameAs
• android:value: ค่า URL sameAs

ดูรายละเอียดเพิ่มเติมได้ที่การจับคู่ค่าพารามิเตอร์แบบแจกแจง

ตัวเลือกการดำเนินการตาม Intent

คุณกําหนดองค์ประกอบ intent ภายใน <capability> เพื่อประกาศวิธีที่ Assistant จะตอบสนองหรือดําเนินการตามคําสั่งเสียงของผู้ใช้ที่ตรงกับความสามารถดังกล่าว การกำหนดค่าวิธีที่ intent เปิดใช้งานปลายทางการจำหน่ายสินค้าในแอปมีหลายวิธี โดยขึ้นอยู่กับโครงสร้างการนําทางของแอป

ตัวเลือกการจำหน่ายที่ใช้ได้มีดังนี้

• Intent ที่ชัดเจน: เปิดคอมโพเนนต์แอปที่เฉพาะเจาะจงโดยกำหนดแอตทริบิวต์ targetClass และ targetPackage สำหรับ intent ซึ่งเป็นวิธีการดำเนินการของแอปที่แนะนำ

• Deep Link: เปิดปลายทางแอปโดยใช้ Deep Link ของ Android โดยกําหนดแท็ก <url-template> ภายในองค์ประกอบ intent วิธีนี้มีประโยชน์หากการนำทางของแอปใช้ Deep Link อยู่แล้ว

• ข้อมูล Intent: คุณสามารถระบุ URI การจำหน่ายสินค้าในแอตทริบิวต์ intent android:data ระบบจะเขียนทับข้อมูล <url-template> ลงในช่องนี้หากมีการกําหนดแท็กนั้นภายใน intent ด้วย

หมายเหตุ: ตัวเลือกการจำหน่ายเหล่านี้ใช้ร่วมกันไม่ได้ เช่น หากกำหนด intent ที่ชัดเจนโดยใช้แอตทริบิวต์ targetClass และ targetPackage ก็ไม่จำเป็นต้องกำหนด <url-template> ด้วย

ข้อมูลพารามิเตอร์และการจับคู่

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

หรือจะประกาศแท็ก <url-template> ใน capability ที่มีตัวยึดตําแหน่งสําหรับพารามิเตอร์แบบไดนามิกก็ได้ เทมเพลตนี้จะแมปกับกิจกรรม Android รายการใดรายการหนึ่งโดยใช้ App Links URL, สคีมที่กำหนดเอง หรือ URL ตาม Intent

การใช้ Intent Extras

ตัวอย่างต่อไปนี้แสดง Intent ที่ชัดเจนซึ่งกําหนดไว้สําหรับการตอบสนอง capability

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

จากตัวอย่างข้างต้น สําหรับคําค้นหาของผู้ใช้ เช่น "Ok Google เริ่มการวิ่ง" แอปจะได้รับ intent ที่เรียกใช้คอมโพเนนต์ ดังนี้ targetPackage, targetClass คอมโพเนนต์ได้รับ Extra ด้วย key = "exercise", value = "Running"

การใช้เทมเพลต URL สําหรับ Deep Link ของ Android

หากแอปจัดการ URL ที่ลิงก์กับแอปซึ่งมีพารามิเตอร์แบบไดนามิกได้อยู่แล้ว คุณก็กำหนด <url-template> ใน intent เพื่อสร้าง Deep Link ของ Android สำหรับการจำหน่ายได้ ตัวอย่างต่อไปนี้จะกําหนด <url-template>

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

จากตัวอย่างข้างต้น เมื่อผู้ใช้ค้นหาว่า "Ok Google เริ่มการวิ่ง" แอปจะได้รับ URL ที่สร้างขึ้น ซึ่งก็คือ "myapp://start?exercise=Running"

หมายเหตุ: หาก URL ที่สร้างขึ้นสําหรับ intent โดยใช้ <url-template> สําหรับการดําเนินการมีการลิงก์กับแอป และมีการเพิ่มตัวกรอง Intent ที่เกี่ยวข้องในไฟล์ทรัพยากร AndroidManifest.xml ก็ไม่จำเป็นต้องกําหนดแอตทริบิวต์ targetClass และ targetActivity ใน intent

หากต้องการแมปพารามิเตอร์ BII กับตําแหน่งใน URL ให้ใช้แอตทริบิวต์ android:name ของแท็ก <parameter> แอตทริบิวต์นี้ตรงกับค่า android:key ในเทมเพลต URL ที่ต้องการแทนที่ด้วยข้อมูลจากผู้ใช้ ค่า android:key ต้องอยู่ใน <url-template> และอยู่ในวงเล็บปีกกา ({})

จับคู่ค่าพารามิเตอร์ที่แจกแจง

พารามิเตอร์ BII บางรายการระบุค่าที่ระบุรายการสำหรับความตั้งใจในการดำเนินการ เช่น ค่าข้อความที่รองรับของ BII RECORD_FOOD_OBSERVATION สำหรับพารามิเตอร์เหล่านี้ Assistant จะจับคู่การค้นหาของผู้ใช้ ("Breakfast") กับเอนทิตีที่มีค่า sameAs ตรงกับ URL สคีมา enum (https://schema.googleapis.com/MealTypeBreakfast) หากต้องการเชื่อมโยงค่า enum สำหรับ entity ที่รองรับ คุณต้องประกาศการเชื่อมโยง sameAs ใน shortcut ตัวอย่างต่อไปนี้แสดงการเชื่อมโยง sameAs สําหรับทางลัดเอนทิตีในบรรทัด

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

ในตัวอย่างข้างต้น หากความสามารถ RECORD_FOOD_OBSERVATION ทริกเกอร์การจับคู่สำหรับประเภทอาหาร "breakfast" ระบบจะส่งข้อมูลเพิ่มเติมต่อไปนี้พร้อมกับการตอบสนอง intent

• key = "for_meal"
• value = "meal_breakfast"

ฟีเจอร์

ฟีเจอร์การดําเนินการของแอปต่อไปนี้พร้อมใช้งานใน shortcuts.xml

พื้นที่โฆษณาในบรรทัดสําหรับการดําเนินการของแอป

สำหรับพารามิเตอร์ BII บางรายการ คุณสามารถใช้แป้นพิมพ์ลัดเพื่อนำทางการดึงข้อมูลเอนทิตีไปยังชุดเอนทิตีที่รองรับซึ่งระบุไว้ใน shortcuts.xml หรือที่เรียกว่าพื้นที่โฆษณาในบรรทัด โปรดดูรายละเอียดที่หัวข้อพื้นที่โฆษณาในบรรทัด

ความตั้งใจที่กําหนดเอง

คุณสามารถประกาศ Intent ที่กําหนดเองใน shortcuts.xml เพื่อเปิดใช้ฟีเจอร์ด้วยเสียงในแอปที่ไม่ตรงกับ BII ที่พร้อมใช้งาน แม้ว่าจะคล้ายกับคำจำกัดความ BII ในด้านฟังก์ชันการทำงาน แต่ Intent ที่กําหนดเองต้องมีแอตทริบิวต์เพิ่มเติม 2 รายการใน shortcuts.xml ดังนี้

• app:queryPatterns: ทรัพยากรอาร์เรย์ที่ประกาศรูปแบบการค้นหาที่แตกต่างกันสำหรับ Intent ที่กําหนดเอง

• android:mimeType: ประเภทพารามิเตอร์ของความตั้งใจที่กําหนดเอง ช่องนี้ไม่จําเป็นสําหรับ BII ที่ทราบประเภทพารามิเตอร์ สําหรับพารามิเตอร์ Intent ที่กําหนดเอง คุณต้องประกาศประเภทเชิงอรรถที่รองรับ

โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อIntent ที่กําหนดเอง