Web envanteri

Uygulama İşlemleri sayesinde kullanıcılar, "Ok Google, Ornek Uygulamasında Three Dot Cafe menüsünü göster." gibi bir komut vererek doğrudan uygulamanızın içeriğine erişebilir. Bu işleve derin bağlantı denir ve kullanıcılarınızın uygulamanızla işlerini tamamlamalarını kolaylaştırabilir.

Google Asistan bu tür bir isteği yerine getirmek için uygulamanızdaki eşleşen içeriğe giden bir derin bağlantı oluşturur. Web sitenizi içerik veya ürün bilgileriyle etkin bir şekilde yönetiyorsanız ve uygulama içi derin bağlantılarınız bu herkese açık web içeriği etrafında düzenlenmişse Asistan'ı web envanteri kullanarak web sitenizden işlem karşılamanın URL'lerini alacak şekilde yapılandırabilirsiniz.

Web envanteri, uygulamanız tarafından desteklenen öğe URL'lerinin web sitesi konumudur. Bir kullanıcı Uygulama İşleminizi çağırdığında Asistan, kullanıcı sorgusunu (ör. "Three Dot Cafe") Android uygulamanız için shortcuts.xml bölümünde belirttiğiniz web sitesinin Google arama dizinindeki karşılık gelen URL'lerle eşleştirir.

Avantajlar

Web envanteri, kullanıcıların uygulamada görüntülediği veya sipariş ettiği öğe listelerinden oluşan büyük ve düzenli olarak güncellenen listelere sahip uygulamalar için avantajlar sunar:

  • Uygulamanızdaki öğe listelerini depolayan satır içi envanter verilerinin aksine web envanteri verileri, web sitenizde bulunur. Asistan'ın web verilerine erişmesine izin vermek, yalnızca uygulamanın yeni bir sürümünün yayınlanmasıyla güncellenebilecek eski satır içi envanter verilerinin riskini önler.

  • Satır içi envanterler 1.000 öğeyle sınırlıdır. Buna karşın, web envanterinin öğe sınırı yoktur ve ihtiyaçlarınıza göre büyüyebilir.

  • Web envanteri, karşılama işleminizin yalnızca web sitenizden alınan öngörülebilir içerik URL'lerini işlemesini sağlayarak uygulama mantığını basitleştirebilir. Buna karşılık, bir envanter yapılandırılmazsa Asistan, amaç parametrelerini bir URL şablonundaki değişkenlerle eşleyerek istek karşılama için derin bağlantılar oluşturur. Ardından, bir kullanıcının uygulamanızda desteklenen bir varlık isteyip istemediğini belirlemek için istek karşılama işleminizin dinamik olarak oluşturulmuş bu URL'yi analiz etmesi gerekir.

Nasıl çalışır?

Asistan, bir Uygulama İşlemi sırasında shortcuts.xml içinde tanımladığınız yerleşik amaçlar (BII'ler) aracılığıyla uygulama içeriğine derin bağlantı verir. Asistan, kullanıcının isteğindeki alakalı öğeleri tanımlamak için doğal dil işlemeyi kullanır ve bunları BII parametrelerine çıkarır. Asistan, daha sonra shortcuts.xml. API'sindeki sipariş karşılama yapılandırmanıza göre parametreleri kullanarak bir derin bağlantı oluşturur

İstek karşılama için derin bağlantı oluşturmanın üç yöntemi vardır:

  • Parametre eşleme: Amaç parametrelerini, istek karşılama URL'si şablonundaki yer tutucularla eşler.
  • Satır içi envanter: Amaç parametrelerini uygulamada tanımlanan desteklenen bir entities listesiyle eşleştirir.
  • Web envanteri: Amaç parametrelerini bir web sitesinin Google arama dizininde bulunan içerikle eşleştirir.

Web envanteri, bir uygulama tarafından desteklenen varlık grubunu temsil eden https://www.exampleapp.com/restaurants/.* gibi geliştirici tarafından tanımlanmış bir web sitesi URL kalıbıdır.

Web envanteri için bir BII parametresi yapılandırılmışsa Asistan, kullanıcı sorgusuyla varlık eşleştirme gerçekleştirmek için web sitesini sorgular. Daha sonra Asistan, yapılandırılmış URL kalıbıyla (ör. https://www.exampleapp.com/restaurants/three-dot-cafe) eşleşen URL sonuçlarını istek karşılama mantığınıza iletir.

Şekil 1. Bir restoran varlığı öğesini almak için web envanterini kullanan örnek bir Asistan sorgusu.

Desteklenen yerleşik intentler

Web envanteri, belirli amaç parametreleri için aşağıdaki BBI'ler tarafından desteklenir:

  • [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]

Web envanteri ekleme

Desteklenen bir BII'yi belirledikten sonra, shortcuts.xml öğesini web sitenizle ilgili ayrıntılarla güncelleyerek web envanteri için etkinleştirirsiniz. shortcuts.xml dosyası, Android projenizde yer alan bir kaynaktır. Uygulamanızın işlevselliğiyle eşlenen BBI'leri tanımlar ve her bir BII'nin, uygulamanızın yerine getirmesi için derin bağlantıları nasıl oluşturması gerektiğini tanımlarsınız. shortcuts.xml hakkında daha fazla bilgi için shortcuts.xml oluşturma bölümüne bakın.

Desteklenen bir BII için web envanterini kullanmak istiyorsanız aşağıdaki adımları uygulayın:

  1. Uygulamanızın shortcuts.xml dosyasına, web envanteriyle kullandığınız bir BII'nin adına ayarlanmış android:name özelliğine sahip bir <capability> etiketi ekleyin. Örneğin: actions.intent.ORDER_MENU_ITEM.

  2. <capability> etiketine, android:action özelliği bu amaç tarafından etkinleştirilecek görünümün adına ayarlanmış bir <intent> etiketi ekleyin.

  3. Aynı <intent> etiketine bir <parameter> etiketi ekleyin ve bu etiketin android:name özelliğini, web sayfalarınız tarafından açıklanan varlığa en yakın değere karşılık gelen BII parametresine ayarlayın. Örneğin, ORDER_MENU_ITEM için web envanteri sağlarken menü sayfalarını menuItem.name hesabına bağlamanız gerekir.

  4. Yeni <parameter> etiketine bir <data> etiketi ekleyin ve android:pathPattern özelliğini, web envanteri için kullanmak istediğiniz yolun URL kalıbına ayarlayın.

Bu adımları kullanarak shortcuts.xml hizmetini yapılandırdığınızda Asistan, android:pathPattern özelliğinde sağladığınız URL kalıbının Google arama dizininden web içeriği alabilir. Daha sonra Asistan, tanımladığınız URL yolu kalıbıyla eşleşen sonuçları kullanarak karşılamanıza bir URL değeri sağlar. Daha sonra uygulamanız, Asistan'ın sağladığı URL verilerine göre kullanıcıyı uygulamanızda belirli bir yere yönlendirir.

Örneğin, web siteniz https://www.examplecafe.com/items/ ile başlayan bir URL yolu kullanan ürün listelemeleri içeriyor. pathPattern https://www.examplecafe.com/items/.* değerini kullanırsınız ve Asistan, https://www.examplecafe.com/items/item123 gibi bir istek karşılama URL'sini bulmak için web aramasında bu URL kalıbını kullanır.

Asistan eşleşen bir web envanteri URL'si bulursa, istek karşılama amacının <data> alanında bu URL'yi bir derin bağlantı gibi sağlar. URL'yi Uri nesnesi olarak almak için amacın getData() yöntemini kullanın. Amacı alan uygulama etkinliği, URL'yi yorumlamaktan ve uygun uygulama kullanıcı arayüzünü etkinleştirmekten sorumludur.

Örnek shortcuts.xml

Aşağıdaki örnekte, menuItem.name BII parametresini içeren istekler için URL sonuçları döndürecek bir web envanteri sağlayan ORDER_MENU_ITEM BII tanımlanmaktadır:

<?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>

Yukarıdaki örnekte menuItem.name için bir pathPattern belirtilerek Asistan'a yalnızca URL kalıbıyla eşleşen URL'leri döndürmesi için talimat verilir: https://www.examplecafe.com/items/.*

Web envanterini destekleyen diğer shortcuts.xml BII örneğini referans belgelerinde bulabilirsiniz.

Eksik sonuçlar için yedeği işleme

Web envanteri sonuçlarının, karşılamanıza döndürülmediği durumlarda uygulamanızın, işlemi mümkün olan en iyi kullanıcı deneyimiyle gerçekleştirmek için yedek mantığı uygulaması gerekir. Eksik sonuçlara neden olan durumlar şunlardır:

  • Eksik amaç parametresi: Kullanıcı, sorgusunda beklenen bir parametreyi atlar veya Asistan, kullanıcı isteğindeki parametreyi anlamamıştır.
  • Eksik URL sonucu: Asistan, web sitenizde kullanıcı sorgusuyla eşleşen bir varlık bulamadı.

Bir özellik için birden fazla <intent> öğesi tanımlayarak eksik parametre değerlerini düzeltebilirsiniz. Asistan ilk niyeti karşılayamazsa bir sonraki amaca geri döner ve bu şekilde devam eder.

Yedek amaçlar parametre gerektirmemelidir. Bunun yerine, kullanıcı sorgusu için arama sonuçlarını görüntüleme gibi daha genel bir derin bağlantıyla özelliği yerine getirmelidir.

Aşağıdaki shortcuts.xml örneğinde ORDER_MENU_ITEM BII iki karşılamayı tanımlar: İlki, menuItem.name parametresinden bir URL bekler. İkincisi ise herhangi bir parametre gerektirmeden kullanıcıyı tüm menü öğelerini gösteren bir sayfaya yönlendirir.

<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>

Bir web envanteri URL'sinin döndürülmediği durumlarda, kullanıcı sorgusunun içeriği yedek amaçlarda kullanılmaya devam edebilir (örneğin, arama sonuçlarını görüntülemek için).

Aşağıdaki shortcuts.xml örneğinde iki amaç öğesi tanımlanmıştır:

  1. İlki, menuItem.name parametresinden bir web envanteri derin bağlantısı gerektirir.
  2. Derin bağlantı döndürülmezse ikinci amaç, varsa menuItem.name kaynaklı kullanıcı sorgusunu kullanarak arama sonuçlarını görüntüler.
<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>

Web envanteri ile uygulama içi arama ekleme

Web envanterini actions.intent.GET\_THING BII uygulamasıyla birleştirerek kullanıcıların uygulamanızda web içeriğini aramasını sağlayabilirsiniz.

Bu BII, bir uygulamadaki varsayılan uygulama içi arama özelliğini kullanarak içerik veya varlıklar arar ve "Ok Google, SampleApp'te şelale yürüyüşlerini göster" gibi sorgular sağlar. GET_THING BII tarafından iletilen thing.name özelliği parametresi için web envanterini yapılandırdığınızda, istek karşılama için web sitenizden eşleşen varlık sonuçları iletilir.

Web envanteri shortcuts.xml örnekleri için GET\_THING BII referansına bakın.

Web envanterini test etme

Bir BII karşılaması için web envanteri tanımladığınızda Asistan, belirtilen BII parametresi için tanımladığınız urlTemplate kalıbıyla eşleşen web sonuçlarını kullanarak derin bağlantı oluşturur. Bir web envanteri sonucu bulunamazsa Asistan, yedek amacınızın urlTemplate kalıbıyla eşleşen bir URL oluşturur. Asistan'ın sağladığı bağlantıların web envanteri urlTemplate kalıplarınızla eşleşen URL'ler olduğunu doğrulayarak web envanteri uygulamanızı test edebilirsiniz.

Aşağıdaki ORDER_MENU_ITEM BII örneğinde Asistan, menuItem.name parametresinde belirtilen urlFilter kalıbıyla eşleşen web envanteri karşılama bağlantıları oluşturur. Örneğin: https://www.examplecafe.com/items/nuggets. İkinci amaç, menuItem.name değerini alır ve ilk amaç URL kalıbıyla eşleşmezse bir arama gerçekleştirir.

<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>

Fiziksel veya sanal bir cihazda web envanterini test etmek için Uygulama İşlemleri Test Aracı'nı kullanın.

Test aracını kullanmak için aşağıdaki adımları izleyin:

  1. Test cihazınızı çalışan uygulamanıza bağlayın.
  2. Android Studio'da Araçlar > Uygulama İşlemleri > Uygulama İşlemleri Test Aracı'na gidin.
  3. Önizleme oluştur'u tıklayın.
  4. Android Studio'da, uygulamanızı test cihazınızda çalıştırın.
  5. Uygulama İşleminizi test etmek için test cihazınızdaki Asistan uygulamasını kullanın. Örneğin, "Ok Google, ExampleCafe'de nugget sipariş et" gibi bir şey diyebilirsiniz.
  6. İstenen işlem sonucunu doğrulamak için uygulamanızın davranışını gözlemleyin veya Android Studio hata ayıklayıcıyı kullanın.