맞춤 인텐트

모든 앱이 서로 다르므로, 모든 앱 기능이 사용 가능한 앱 작업 내장 인텐트(BII)와 일치하지는 않습니다. 앱 기능에 맞는 BII가 없는 경우 맞춤 인텐트를 대신 사용하여 앱 작업으로 앱을 확장할 수 있습니다.

BII와 마찬가지로 맞춤 인텐트는 shortcuts.xml 스키마를 따르며 어시스턴트와 정의된 처리 간의 연결점 역할을 합니다. 맞춤 인텐트에도 관련 처리에서 매개변수에 매핑할 수 있는 인텐트 매개변수가 있습니다.

BII와 달리 맞춤 인텐트에는 사용자가 말할 수 있는 쿼리 예를 설명하는 쿼리 패턴이 필요합니다. 이 방법은 사용자가 관련 인텐트를 표현하는 일반적인 방법을 모델링하는 내장 인텐트와는 다릅니다.

제한사항

맞춤 인텐트에는 다음과 같은 제한사항이 있습니다.

  • 맞춤 인텐트의 이름은 actions.intent로 시작할 수 없습니다.
  • 맞춤 인텐트의 이름은 앱의 맞춤 인텐트 이름 간에 고유해야 합니다.
  • Google 어시스턴트를 통한 매개변수 추출에는 특정 데이터 유형만 사용할 수 있습니다(지원 유형 참고).
  • 맞춤 인텐트는 사용 가능한 쿼리 패턴의 예를 포함해야 합니다(쿼리 패턴 참고).
  • 각 쿼리는 최대 2개의 텍스트 매개변수를 지원합니다. 이 제한은 다른 데이터 유형에는 적용되지 않습니다.
  • 맞춤 인텐트는 en-US 언어만 지원합니다. 또한 기기 및 어시스턴트 언어 설정이 일치해야 합니다.

지원 유형

맞춤 인텐트는 매개변수 추출에 다음 schema.org 유형을 지원합니다.

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

맞춤 인텐트로 앱 작업 정의

BII를 사용하는 다른 앱 작업과 마찬가지로 shortcuts.xml의 <capability> 요소에서 맞춤 인텐트를 정의할 수 있습니다.

기능은 <shortcuts> 루트 요소에 정의됩니다. <shortcuts> 요소를 정의할 때는 다음 예와 같이 액세스하려는 속성의 네임스페이스를 포함합니다.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

android:name 속성에 맞춤 인텐트의 이름을 입력하고 queryPatterns 속성에서 쿼리 패턴 리소스 파일을 참조합니다.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

맞춤 인텐트 이름은 actions.intent로 시작할 수 없습니다. 네임스페이스가 BII용으로 예약되어 있기 때문입니다. 대신 맞춤 인텐트의 이름을 지정할 때는 접두사 custom.actions.intent를 사용하여 다르게 작동하는 BII 및 Android 인텐트와 맞춤 인텐트를 구별하세요.

지원되는 schema.org 유형 중 매개변수 의미를 가장 잘 설명하는 유형을 각 매개변수에 제공합니다. 예를 들어 수신 예상 날짜를 표현하려면 https://schema.org/Date를 사용하면 됩니다.

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

BII의 바로가기와 동일한 형식을 사용하여 shortcuts.xml에서 맞춤 인텐트의 바로가기를 정의합니다.

다음 코드에서는 참조된 쿼리 패턴을 사용하여 SCHEDULE_APPOINTMENT 맞춤 인텐트를 트리거하고 apptType 매개변수에 대해 정의된 값 집합 DRIVERS_LICENSE와 VEHICLE_REGISTRATION을 사용하는 앱 작업을 설명합니다.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

인라인 인벤토리와 함께 맞춤 인텐트 매개변수를 구성할 수 있습니다. 이렇게 하면 항목 추출을 shortcuts.xml에 지정된 지원되는 항목 집합으로 보낼 수 있습니다.

쿼리 패턴

사용하는 각 맞춤 인텐트에는 그 인텐트와 관련해 사용자로부터 예상되는 일련의 쿼리가 필요합니다. 이 방법은 사용자가 원하는 작업 또는 찾는 정보를 표현하는 일반 방식에 관해 쿼리가 이미 모델링된 BII와는 다릅니다.

Android 리소스 파일(일반적으로 /res/values/strings.xml)에서 쿼리 패턴을 문자열 배열의 항목으로 지정합니다. 앱 작업이 호출되면 Google 어시스턴트는 처리를 위해 사용자 인텐트를 일치시키는 작업의 일부로, 사용자 쿼리를 쿼리 패턴과 비교하여 확인합니다. 제공하는 각 쿼리 패턴은 상응하는 맞춤 인텐트에 유효하다고 간주된 문구를 표현하게 됩니다.

맞춤 인텐트의 쿼리 패턴을 제공할 경우 각 패턴은 'Example App을 열고' 또는 'Example App을 시작하고'와 같은 명시적 호출을 따라야 합니다. 예를 들어 다음 사용자 쿼리를 생각해 보세요.

  • "Hey Google, Example Game App을 열고 케이크를 만들어 줘."
  • "Hey Google, Example Game App을 열고 애플파이를 만들어 줘."
  • "Hey Google, Example Game App을 시작하고 케이크 5개를 만들어 줘."
  • "Hey Google, Example Game App을 사용하여 케이크를 다섯 번 만들어 줘."

사용자 쿼리를 일치시키려면 호출 구문 이후의 쿼리 부분이 포함된 쿼리 패턴을 제공합니다. 쿼리에서 추출하려는 정보(예: 사용자가 제공한 텍스트 또는 숫자)의 경우 값을 쿼리 패턴의 자리표시자와 함께 상응하는 인텐트 매개변수에 할당합니다.

쿼리 패턴에서 매개변수를 참조하려면 패턴의 매개변수 이름에 $를 추가합니다. 예를 들어 <parameter name="date1" ...(actions.xml에서) 또는 <parameter android:name="date1" ...(shortcuts.xml에서)과 같은 매개변수의 자리표시자 값을 만들려면 $date1을 사용합니다.

다음 코드에서는 위 사용자 쿼리와 일치하는 쿼리 패턴을 설명하고 항목 이름의 값과 만들 항목 수를 추출합니다.

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

쿼리 패턴에는 조건문이 지원됩니다. set (an)? appointment $date $time을 예로 들 수 있습니다. '오늘 정오에 약속 잡기'와 '오늘 정오에 약속 하나 잡기'가 모두 유효한 쿼리입니다.