웹 인벤토리

앱 작업을 사용하면 사용자는 "Hey Google, ExampleApp에서 쓰리닷 카페 메뉴를 보여 줘"와 같은 말을 해서 앱 콘텐츠로 바로 이동할 수 있습니다. 이 기능을 딥 링크라고 하며, 사용자가 앱에서 일을 손쉽게 처리할 수 있도록 해 주는 기능입니다.

이러한 유형의 요청을 처리하기 위해 Google 어시스턴트는 앱 내 일치하는 콘텐츠로 연결되는 딥 링크를 생성합니다. 콘텐츠 또는 제품 정보로 웹사이트를 적극적으로 유지관리하고 인앱 딥 링크가 공개 웹 콘텐츠를 중심으로 구성된 경우, 웹 인벤토리를 사용하여 작업 처리 URL을 웹사이트에서 가져오도록 어시스턴트를 구성할 수 있습니다.

웹 인벤토리는 앱에서 지원하는 항목 URL의 웹사이트 위치입니다. 사용자가 앱 작업을 호출하면 어시스턴트가 '쓰리닷 카페'와 같은 사용자 쿼리를 Android 앱의 shortcuts.xml에 지정된 웹사이트의 Google 검색 색인에 있는 상응하는 URL에 일치시킵니다.

이점

웹 인벤토리는 사용자가 앱에서 보거나 주문하는 항목 목록이 많고 정기적으로 이를 업데이트하는 앱에 유용합니다.

  • 웹 인벤토리 데이터는 앱에 항목 목록을 저장하는 인라인 인벤토리 데이터와 달리 웹사이트에 존재합니다. 웹 데이터에 액세스하도록 어시스턴트에 허용하면 앱의 새 버전을 게시해야만 업데이트되는 인라인 인벤토리 데이터가 갖는 부실 위험을 피할 수 있습니다.

  • 인라인 인벤토리는 항목 1,000개로 제한됩니다. 반면 웹 인벤토리는 항목 제한이 없으므로 필요에 따라 확장 가능합니다.

  • 웹 인벤토리는 웹사이트에서 가져온 예측 가능한 콘텐츠 URL만 취급하도록 처리에 허용하기 때문에 앱 로직을 단순화할 수 있습니다. 반면, 인벤토리가 구성되어 있지 않으면 어시스턴트는 인텐트 매개변수를 URL 템플릿의 변수에 매핑하여 처리 딥 링크를 생성합니다. 그러면 처리에서는 사용자가 앱에서 지원되는 항목을 요청했는지 확인하기 위해 동적으로 생성된 이 URL을 분석해야 합니다.

작동 방식

앱 작업 중에 어시스턴트는 shortcuts.xml에 정의된 내장 인텐트(BII)를 통해 앱 콘텐츠에 딥 링크를 연결합니다. 어시스턴트는 자연어 처리를 사용하여 사용자 요청에서 관련 항목을 식별하고 이를 BII 매개변수로 추출합니다. 그런 다음 어시스턴트는 shortcuts.xml.의 처리 구성에 따라 매개변수를 사용하여 딥 링크를 생성합니다.

처리 딥 링크를 생성하는 방법에는 세 가지가 있습니다.

  • 매개변수 매핑: 인텐트 매개변수를 처리 URL 템플릿의 자리표시자에 매핑합니다.
  • 인라인 인벤토리: 인텐트 매개변수를 앱에 정의된 지원되는 entities 목록과 일치시킵니다.
  • 웹 인벤토리: 인텐트 매개변수를 웹사이트의 Google 검색 색인에서 발견된 콘텐츠와 일치시킵니다.

웹 인벤토리는 https://www.exampleapp.com/restaurants/.*와 같이 개발자가 정의한 웹사이트 URL 패턴으로, 앱에서 지원하는 항목의 항목 집합을 나타냅니다.

웹 인벤토리에 BII 매개변수가 구성된 경우 어시스턴트는 웹사이트를 쿼리하여 사용자 쿼리와 항목을 일치시킵니다. 그런 다음 어시스턴트는 구성된 URL 패턴과 일치하는 URL 결과(예: https://www.exampleapp.com/restaurants/three-dot-cafe)를 처리에 전달합니다.

그림 1. 웹 인벤토리를 사용하여 레스토랑 항목을 검색하는 어시스턴트 쿼리의 예

지원되는 내장 인텐트

특정 인텐트 매개변수의 경우 웹 인벤토리는 다음 BII를 통해 지원됩니다.

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

웹 인벤토리 추가

지원되는 BII를 식별했으면 웹사이트 세부정보로 shortcuts.xml을 업데이트하여 그 BII를 웹 인벤토리에 사용 설정합니다. shortcuts.xml 파일은 Android 프로젝트의 리소스입니다. 여기서 앱의 기능에 매핑되는 BII를 정의하고, 각 BII가 앱에서 처리할 딥 링크를 어떻게 생성할지 정의할 수 있습니다. shortcuts.xml에 관한 자세한 내용은 shortcut.xml 만들기를 참고하세요.

지원되는 BII에 웹 인벤토리를 사용하려면 다음 단계를 따릅니다.

  1. 앱의 shortcuts.xml 파일에서 android:name 속성이 웹 인벤토리로 처리 중인 BII의 이름으로 설정된 상태(예: actions.intent.ORDER_MENU_ITEM)에서 <capability> 태그를 추가합니다.

  2. android:action 속성이 이 인텐트로 활성화할 뷰 이름으로 설정된 <intent> 태그를 <capability> 태그에 추가합니다.

  3. 동일한 <intent> 태그에서 <parameter> 태그를 추가하고, 웹페이지에 설명된 항목에 가장 근접한 BII 매개변수에 android:name 속성을 설정합니다. 예를 들어 ORDER_MENU_ITEM을 위한 웹 인벤토리를 제공할 경우 메뉴 페이지를 menuItem.name에 연결해야 합니다.

  4. 새 <parameter> 태그에서 <data> 태그를 추가하고, 웹 인벤토리에 사용할 경로의 URL 패턴에 android:pathPattern 속성을 설정합니다.

이러한 단계를 통해 shortcuts.xml을 구성하면 어시스턴트는 android:pathPattern 속성에 제공된 URL 패턴의 Google 검색 색인에서 웹 콘텐츠를 검색할 수 있습니다. 그런 다음 어시스턴트는 정의된 URL 경로 패턴과 일치하는 결과를 사용하여 처리에 URL 값을 제공합니다. 그러면 앱은 어시스턴트가 제공한 URL 데이터를 기반으로 사용자를 앱의 특정 위치로 안내합니다.

예를 들어 https://www.examplecafe.com/items/로 시작하는 URL 경로를 사용하는 제품 등록정보가 웹사이트에 포함되어 있다고 가정해 보겠습니다. pathPattern 값 https://www.examplecafe.com/items/.*이 사용되면 어시스턴트는 웹 검색에 이 URL 패턴을 사용하여 https://www.examplecafe.com/items/item123 같은 처리 URL을 찾습니다.

어시스턴트가 일치하는 웹 인벤토리 URL을 찾으면 처리 인텐트의 <data> 필드에 그 URL을 딥 링크인 것처럼 제공합니다. 인텐트의 getData() 메서드를 사용하여 URL을 Uri 객체로 가져옵니다. 인텐트를 수신하는 앱 활동이 URL을 해석하고 적절한 앱 사용자 인터페이스를 활성화하는 일을 담당합니다.

shortcuts.xml 예

다음 샘플에서는 ORDER_MENU_ITEM BII를 정의합니다. menuItem.name BII 매개변수가 포함된 요청의 URL 결과를 반환하기 위한 웹 인벤토리를 제공하는 BII입니다.

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

위 샘플에는 menuItem.name에 pathPattern이 지정되어 있고, 이로 인해 URL 패턴(https://www.examplecafe.com/items/.*)과 일치하는 URL만 반환하도록 어시스턴트에 지시됩니다.

웹 인벤토리를 지원하는 BII의 더 많은 shortcuts.xml 예는 참조 문서에서 확인할 수 있습니다.

누락된 결과의 대체 처리

웹 인벤토리 결과가 처리에 반환되지 않으면 앱은 가능한 최적의 사용자 환경으로 그 작업을 처리하기 위해 대체 로직을 구현해야 합니다. 결과가 누락되는 상황은 다음과 같습니다.

  • 인텐트 매개변수 누락: 사용자가 쿼리에 필요한 매개변수를 생략했거나 어시스턴트가 사용자 요청에서 매개변수를 이해하지 못했습니다.
  • URL 결과 누락: 어시스턴트가 사용자 쿼리와 일치하는 항목을 웹사이트에서 찾을 수 없습니다.

기능에 관한 여러 개의 <intent> 요소를 정의하여 누락된 매개변수 값을 처리할 수 있습니다. 어시스턴트가 첫 번째 인텐트를 충족할 수 없으면 그다음 인텐트로 변경하는 식입니다.

대체 인텐트에는 매개변수가 필요하지 않습니다. 대신 대체 인텐트는 사용자 쿼리에 관한 검색결과를 표시하는 등 보다 일반적인 딥 링크로 기능을 실행해야 합니다.

다음 샘플 shortcuts.xml에서 ORDER_MENU_ITEM BII는 두 개의 처리를 정의합니다. 첫 번째 처리에는 menuItem.name 매개변수의 URL이 필요합니다. 두 번째 처리에는 매개변수가 필요 없고 모든 메뉴 항목을 표시하는 페이지로 사용자를 라우팅합니다.

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

웹 인벤토리 URL이 반환되지 않더라도 검색결과를 표시하는 경우 등에서 사용자 쿼리의 콘텐츠가 대체 인텐트에 계속 사용될 수 있습니다.

다음 샘플 shortcuts.xml에는 2개의 인텐트 요소가 정의되어 있습니다.

  1. 첫 번째 요소에는 menuItem.name 매개변수의 웹 인벤토리 딥 링크가 필요합니다.
  2. 딥 링크가 반환되지 않으면 두 번째 인텐트가 menuItem.name의 사용자 쿼리를 사용(있는 경우)하여 검색결과를 표시합니다.
<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>

웹 인벤토리를 사용한 인앱 검색 추가

웹 인벤토리를 actions.intent.GET\_THING BII의 구현과 결합하면 사용자가 앱에서 웹 콘텐츠를 검색할 수 있습니다.

이 BII는 "Hey Google, SampleApp에서 폭포 하이킹을 보여 줘" 같은 쿼리를 사용 설정하여 앱의 기본 인앱 검색 기능으로 콘텐츠 또는 항목을 검색합니다. GET_THING BII에 의해 전달된 thing.name 기능 매개변수에 웹 인벤토리를 구성하면 웹사이트의 일치하는 항목 결과가 처리를 위해 전달됩니다.

웹 인벤토리 shortcuts.xml 샘플은 GET\_THING BII 참조를 확인하세요.

웹 인벤토리 테스트

BII 처리를 위한 웹 인벤토리를 정의하면 어시스턴트는 지정된 BII 매개변수에 정의된 urlTemplate 패턴과 일치하는 웹 결과를 사용하여 딥 링크를 생성합니다. 웹 인벤토리 결과를 찾을 수 없으면 어시스턴트는 대체 인텐트의 urlTemplate 패턴과 일치하는 URL을 생성합니다. 어시스턴트가 제공하는 링크가 웹 인벤토리 urlTemplate 패턴과 일치하는 URL인지 확인하는 방법으로 웹 인벤토리 구현을 테스트할 수 있습니다.

다음 샘플 ORDER_MENU_ITEM BII에서는 어시스턴트가 menuItem.name 매개변수에 지정된 urlFilter 패턴과 일치하는 웹 인벤토리 처리 링크를 생성합니다(예: https://www.examplecafe.com/items/nuggets). 첫 번째 인텐트가 URL 패턴과 일치시키는 데 실패하면 두 번째 인텐트가 menuItem.name 값을 사용하여 검색합니다.

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

앱 작업 테스트 도구를 사용하여 실제 기기나 가상 기기에서 웹 인벤토리를 테스트합니다.

테스트 도구를 사용하려면 다음 단계를 따르세요.

  1. 테스트 기기를 실행 중인 앱과 연결합니다.
  2. Android 스튜디오에서 Tools > App Actions > App Actions Test Tool로 이동합니다.
  3. Create preview를 클릭합니다.
  4. Android 스튜디오에서 테스트 기기에 앱을 실행합니다.
  5. 테스트 기기에서 어시스턴트 앱을 사용하여 앱 작업을 테스트합니다. 예를 들어 "Hey Google, ExampleCafe에서 너겟 주문해 줘"와 같이 말하면 됩니다.
  6. 원하는 작업 결과인지 앱 동작을 관찰하거나 Android 스튜디오 디버거를 사용하여 확인합니다.