Inventaris web

Dengan Action Aplikasi, pengguna dapat langsung mengakses konten aplikasi Anda dengan mengucapkan hal-hal seperti, “Ok Google, tampilkan menu untuk Kafe Enak di ContohAplikasi.” Fungsi ini disebut deep linking yang dapat memudahkan pengguna untuk menyelesaikan berbagai hal dengan aplikasi Anda.

Untuk memenuhi jenis permintaan ini, Asisten Google akan membuat deep link ke konten yang sesuai di aplikasi Anda. Jika Anda secara aktif menyediakan konten atau informasi produk di situs Anda, dan deep link dalam aplikasi diatur sesuai konten web publik ini, Anda dapat mengonfigurasi Asisten untuk mengambil URL untuk fulfillment tindakan dari situs Anda, menggunakan inventaris web.

Inventaris web adalah lokasi situs dari URL item yang didukung oleh aplikasi Anda. Saat pengguna memanggil Action Aplikasi Anda, Asisten akan mencocokkan kueri pengguna, seperti “Kafe Enak”, dengan URL yang sesuai di indeks penelusuran Google untuk situs yang Anda tentukan di shortcuts.xml untuk aplikasi Android Anda.

Manfaat

Inventaris web menawarkan keuntungan untuk aplikasi dengan daftar item yang besar dan diperbarui secara berkala yang dilihat atau dipesan oleh pengguna di aplikasi:

Data inventaris web berada di situs Anda, tidak seperti data inventaris inline, yang menyimpan daftar item di aplikasi Anda. Mengizinkan Asisten mengakses data web menghindari risiko data inventaris inline yang tidak berlaku, yang hanya dapat diperbarui dengan memublikasikan versi baru aplikasi.
Inventaris inline dibatasi hingga 1.000 item. Sebaliknya, inventaris web tidak memiliki batas item, dan dapat bertambah sesuai kebutuhan Anda.
Inventaris web dapat menyederhanakan logika aplikasi dengan memungkinkan fulfillment Anda hanya menangani URL konten yang dapat diprediksi yang diambil dari situs Anda. Sebaliknya, jika inventaris tidak dikonfigurasi, Asisten akan menghasilkan deep link untuk fulfillment dengan memetakan parameter intent ke variabel dalam template URL. Kemudian, fulfillment Anda harus menganalisis URL yang dihasilkan secara dinamis ini untuk menentukan apakah pengguna meminta entity yang didukung di aplikasi Anda atau tidak.

Cara kerja

Selama Action Aplikasi, Asisten melakukan deep link ke konten aplikasi melalui intent bawaan (BII) yang Anda tentukan di shortcuts.xml. Asisten menggunakan natural language processing untuk mengidentifikasi item yang relevan dalam permintaan pengguna, lalu mengekstraknya ke dalam parameter BII. Asisten kemudian membuat deep link menggunakan parameter, berdasarkan konfigurasi fulfillment Anda di shortcuts.xml.

Ada tiga metode yang tersedia untuk menghasilkan deep link untuk fulfillment:

Pemetaan parameter: Memetakan parameter intent ke placeholder dalam template URL fulfillment.
Inventaris inline: Mencocokkan parameter intent dengan daftar entities yang didukung yang ditentukan dalam aplikasi.
Inventaris web: Mencocokkan parameter intent dengan konten yang ditemukan di indeks penelusuran Google situs.

Inventaris web adalah pola URL situs yang ditentukan developer, seperti https://www.exampleapp.com/restaurants/.*, yang mewakili kumpulan entity dari entity yang didukung oleh aplikasi.

Jika parameter BII dikonfigurasi untuk inventaris web, Asisten akan mengkueri situs untuk melakukan pencocokan entity dengan kueri pengguna. Asisten akan meneruskan hasil URL yang cocok dengan pola URL yang dikonfigurasi, seperti https://www.exampleapp.com/restaurants/three-dot-cafe, ke fulfillment Anda.

**Gambar 1.** Contoh kueri Asisten yang menggunakan inventaris web untuk mengambil item entity restoran.

Intent bawaan yang didukung

Inventaris web didukung, untuk parameter intent tertentu, oleh BII berikut:

[actions.intent.CREATE_REVIEW]
[actions.intent.GET_NEWS_ARTICLE]
[actions.intent.GET_REVIEW]
[actions.intent.GET_THING]
[actions.intent.ORDER_MENU_ITEM]
[actions.intent.GET_EXERCISE_PLAN]
[actions.intent.GET_DIGITAL_DOCUMENT]
[actions.intent.GET_ITEM_LIST]
[actions.intent.GET_OFFER]
[actions.intent.CREATE_OFFER]
[actions.intent.GET_PRODUCT]
[actions.intent.UPDATE_CART]
[actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION]
[actions.intent.GET_IMAGE_OBJECT]
[actions.intent.GET_SOCIAL_MEDIA_POSTING]
[actions.intent.GET_SOCIAL_MEDIA_PROFILE]
[actions.intent.CREATE_TAXI_RESERVATION]
[actions.intent.CREATE_FLIGHT_RESERVATION]
[actions.intent.CREATE_LODGING_RESERVATION]
[actions.intent.GET_LOCAL_BUSINESS]
[actions.intent.GET_RESERVATION]
[actions.intent.UPDATE_RESERVATION]

Menambahkan inventaris web

Setelah mengidentifikasi BII yang didukung, Anda dapat mengaktifkannya untuk inventaris web dengan memperbarui shortcuts.xml dengan detail tentang situs Anda. File shortcuts.xml adalah resource di project Android tempat Anda menentukan BII yang dipetakan ke fungsi aplikasi dan cara setiap BII harus menghasilkan deep link untuk aplikasi Anda agar terpenuhi. Untuk mempelajari shortcuts.xml lebih lanjut, lihat Membuat shortcuts.xml.

Agar dapat menggunakan inventaris web untuk BII yang didukung, ikuti langkah-langkah berikut:

Di file shortcuts.xml untuk aplikasi Anda, tambahkan tag <capability> dengan atribut android:name yang ditetapkan ke nama BII yang Anda tangani dengan inventaris web, misalnya: actions.intent.ORDER_MENU_ITEM.
Dalam tag <capability>, tambahkan tag <intent> dengan atribut android:action yang ditetapkan ke nama tampilan yang akan diaktifkan oleh intent ini.
Pada tag <intent> yang sama, tambahkan tag <parameter> dan tetapkan atribut android:name-nya ke parameter BII yang paling sesuai dengan entity yang dijelaskan oleh halaman web Anda. Misalnya, saat menyediakan inventaris web untuk ORDER_MENU_ITEM, Anda harus menautkan halaman menu ke menuItem.name.
Pada tag <parameter> baru, tambahkan tag <data> dan tetapkan atribut android:pathPattern-nya ke pola URL jalur yang ingin Anda gunakan untuk inventaris web.

Saat Anda mengonfigurasi shortcuts.xml menggunakan langkah-langkah ini, Asisten dapat mengambil konten web dari indeks penelusuran Google pola URL yang Anda sediakan dalam atribut android:pathPattern. Asisten kemudian memberikan nilai URL ke fulfillment Anda menggunakan hasil yang cocok dengan pola jalur URL yang Anda tentukan. Aplikasi Anda kemudian mengarahkan pengguna ke tempat tertentu di aplikasi berdasarkan data URL yang diberikan oleh Asisten.

Misalnya, situs Anda berisi listingan produk yang menggunakan jalur URL yang diawali dengan https://www.examplecafe.com/items/. Anda menggunakan nilai pathPattern https://www.examplecafe.com/items/.*, dan Asisten menggunakan pola URL ini dalam penelusuran web untuk menemukan URL fulfillment, seperti https://www.examplecafe.com/items/item123.

Jika Asisten menemukan URL inventaris web yang cocok, Asisten akan memberikan URL di kolom <data> intent fulfillment, seolah-olah itu adalah deep link. Gunakan metode getData() dari intent ini untuk mendapatkan URL sebagai objek Uri. Aktivitas aplikasi yang menerima intent bertanggung jawab untuk menafsirkan URL dan mengaktifkan antarmuka pengguna aplikasi yang sesuai.

Contoh shortcuts.xml

Contoh berikut menentukan BII ORDER_MENU_ITEM yang menyediakan inventaris web untuk menampilkan hasil URL untuk permintaan yang berisi parameter BII menuItem.name:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

Dalam contoh di atas, pathPattern ditentukan untuk menuItem.name, yang memerintahkan Asisten untuk hanya menampilkan URL yang cocok dengan pola URL: https://www.examplecafe.com/items/.*

Contoh shortcuts.xml BII lainnya yang mendukung inventaris web tersedia di dokumentasi referensi.

Menangani penggantian untuk hasil yang tidak ada

Jika hasil inventaris web tidak dikembalikan ke fulfillment Anda, aplikasi Anda harus menerapkan logika penggantian untuk memenuhi tindakan dengan pengalaman pengguna sebaik mungkin. Situasi yang menyebabkan hasil tidak ada meliputi:

Parameter intent tidak ada: Pengguna menghilangkan parameter yang diharapkan dalam kuerinya atau Asisten tidak dapat memahami parameter dalam permintaan pengguna.
Hasil URL tidak ada: Asisten tidak dapat menemukan entity di situs Anda yang cocok dengan kueri pengguna.

Anda dapat menangani parameter value yang tidak ada dengan menentukan beberapa elemen <intent> untuk suatu kemampuan. Jika tidak dapat memenuhi intent pertama, Asisten akan beralih ke intent berikutnya, dan seterusnya.

Intent penggantian seharusnya tidak memerlukan parameter. Sebaliknya, solusi ini harus memenuhi kemampuan dengan deep link yang lebih umum, seperti menampilkan hasil penelusuran untuk kueri pengguna.

Dalam contoh shortcuts.xml berikut, BII ORDER_MENU_ITEM menentukan dua fulfillment: yang pertama mengharapkan URL dari parameter menuItem.name. Yang kedua tidak memerlukan parameter, dengan mengarahkan pengguna ke halaman yang menampilkan semua item menu.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

Jika URL inventaris web tidak ditampilkan, konten kueri pengguna masih dapat digunakan dalam intent penggantian, misalnya, untuk menampilkan hasil penelusuran.

Dalam contoh shortcuts.xml berikut, dua elemen intent ditentukan:

Yang pertama memerlukan deep link inventaris web dari parameter menuItem.name.
Jika deep link tidak ditampilkan, intent kedua menampilkan hasil penelusuran, menggunakan kueri pengguna dari menuItem.name, jika ada.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Menambahkan penelusuran dalam aplikasi dengan inventaris web

Anda dapat memungkinkan pengguna menelusuri konten web di aplikasi dengan menggabungkan inventaris web dengan penerapan BII actions.intent.GET\_THING.

BII ini menelusuri konten atau entity menggunakan fitur penelusuran dalam aplikasi default dalam sebuah aplikasi, yang memungkinkan kueri seperti: "Ok Google, tampilkan pendakian air terjun di SampleApp". Dengan mengonfigurasi inventaris web untuk parameter kemampuan thing.name yang diteruskan oleh BII GET_THING, hasil entity yang cocok dari situs Anda akan diteruskan untuk fulfillment.

Untuk sampel shortcuts.xml inventaris web, lihat referensi BII GET\_THING.

Menguji inventaris web

Saat Anda menentukan inventaris web untuk fulfillment BII, Asisten menghasilkan deep link menggunakan hasil web yang cocok dengan pola urlTemplate yang Anda tentukan untuk parameter BII yang ditentukan. Jika hasil inventaris web tidak dapat ditemukan, Asisten akan membuat URL yang cocok dengan pola urlTemplate dari intent penggantian Anda. Anda dapat menguji implementasi inventaris web dengan memverifikasi bahwa Asisten link menyediakan URL yang cocok dengan pola urlTemplate inventaris web Anda.

Pada contoh ORDER_MENU_ITEM BII berikut, Asisten membuat link fulfillment inventaris web yang cocok dengan pola urlFilter yang ditentukan dalam parameter menuItem.name, misalnya: https://www.examplecafe.com/items/nuggets. Intent kedua mengambil nilai menuItem.name dan melakukan penelusuran jika intent pertama gagal cocok dengan pola URL.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Gunakan Alat Uji Action Aplikasi untuk menguji inventaris web pada perangkat fisik atau virtual.

Untuk menggunakan alat uji, ikuti langkah-langkah berikut:

Hubungkan perangkat pengujian dengan aplikasi yang sedang berjalan.
Di Android Studio, buka Tools > App Actions > App Actions Test Tool.
Klik Create preview.
Di Android Studio, jalankan aplikasi Anda di perangkat pengujian.
Gunakan aplikasi Asisten di perangkat pengujian untuk menguji Action Aplikasi Anda. Misalnya, Anda dapat mengucapkan, "Ok Google, pesan nugget di ExampleCafe".
Amati perilaku aplikasi Anda, atau gunakan debugger Android Studio, untuk memverifikasi hasil tindakan yang diinginkan.