앱 작업을 통해 Google 어시스턴트로 Android 앱 확장(2단계)

첫 번째 앱 작업 Codelab에서는 건강 및 피트니스 BII 카테고리의 내장 인텐트(BII) 카테고리의 BII를 구현하여 Google 어시스턴트를 샘플 피트니스 앱으로 확장하는 방법을 알아보았습니다. BII는 사용자가 어시스턴트에 자주 요청하는 작업 유형을 나타내는 카테고리로 분류됩니다.

이 Codelab에서는 거의 모든 Android 앱에서 처리할 수 있는 일반적인 앱 작업을 나타내는 [일반 BII 카테고리]의 BII를 사용하여 앱에 앱 작업을 추가하는 방법을 알아봅니다.

이 Codelab에서는 앱 작업을 이용한 개발을 위한 중급 수준의 개념을 다룹니다. Android 앱 개발, 딥 링크 처리, actions.xml 리소스 생성, 앱 작업 테스트 도구 플러그인 사용 경험이 있어야 합니다. 앱 작업이 처음이라면 이전 Codelab부터 시작하는 것이 좋습니다.

빌드할 항목

이 Codelab에서는 두 개의 일반 BII를 샘플 할 일 목록 앱에 추가하여 사용자가 어시스턴트에 다음 작업을 요청할 수 있도록 합니다.

Google 어시스턴트가 앱에서 진행 중인 작업을 표시하는 3개의 단계적 화면

학습할 내용

  • 일반 카테고리 BII를 사용하여 어시스턴트를 대부분의 Android 앱으로 확장하는 방법
  • 앱 작업 테스트 도구 플러그인을 사용하여 일반 BII를 테스트하는 방법

선행 조건

  • git이 설치된 셸 명령어를 실행하는 터미널
  • Android 스튜디오 최신 정식 버전
  • Google Play Console 액세스 권한이 있는 Google 계정
  • Google Play 스토어 액세스 및 작업 테스트를 위한 인터넷 액세스가 가능한 Android 기기 또는 에뮬레이터

이 Codelab에서는 Android 기기(실제 기기 또는 에뮬레이터)를 사용하여 작업을 테스트합니다. 실제 기기를 사용하는 경우 기기가 로컬 개발 머신에 연결되어 있는지 확인하세요. 또한 기기(또는 에뮬레이터)의 Google 앱에 로그인한 상태여야 하며 동일한 Google 계정을 사용하여 Android 스튜디오에 로그인해야 합니다. 기기에 Google 어시스턴트 앱도 설치되어 있어야 합니다.

이 Codelab은 Android용 할 일 목록 샘플 앱으로 시작합니다. 이 샘플 앱의 사용자는 할 일 목록에 항목을 추가하고, 카테고리별로 항목을 검색하고, 완료된 작업에 대한 정보를 볼 수 있습니다.

기본 파일 다운로드

다음 명령어를 실행하여 샘플 앱의 GitHub 저장소를 클론합니다.

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

저장소를 클론한 후 Android 스튜디오에서 엽니다.

  • Welcome to Android Studio 대화상자에서 Import project를 클릭합니다.
  • 저장소를 클론한 폴더를 찾아 선택합니다.

Codelab 완료 후의 Todo 앱 버전을 보려면 --branch master 플래그를 사용하여 샘플 앱 저장소를 클론합니다.

테스트 지원을 위해 Android 애플리케이션 ID 변경

이 Codelab 후반에서 앱 작업 테스트 도구를 사용하여 Android 기기 또는 에뮬레이터에서 작업을 테스트합니다. 테스트 도구를 실행하려면 먼저 앱을 Google Play Console의 프로젝트에 업로드해야 합니다. Play Console에 앱을 업로드할 때 '중복된 패키지 이름' 오류를 방지하기 위해 샘플 앱의 applicationId를 고유하게 변경하세요.

app/build.gradle에서 applicationId 'com.example.myapp' 값을 'com.codelabs.myname'과 같은 고유 ID로 업데이트합니다. 애플리케이션 ID를 결정하는 데 도움이 필요하면 Android 참고 페이지를 확인하세요.

build.gradle

android {
...
    defaultConfig {
        // This ID uniquely identifies your app on the device and in Google Play Store
        applicationId "com.example.myapp"
    ...
    }
}

applicationId를 업데이트하면 IDE에 'Gradle files have changed since last project sync...'라는 노란색 경고 상자가 나타납니다. 이 경우 상자에서 Sync Now를 클릭하여 Play Console에 앱을 업로드할 때 발생할 수 있는 문제를 예방합니다.

기기에서 앱 테스트

앱을 변경하기 전에 샘플 앱의 기능을 확인하면 도움이 될 수 있으니 에뮬레이터에서 앱을 실행해 봅니다.

  • Android 스튜디오에서 Run > Run app을 선택하거나 툴바에서 Run을 클릭합니다.
  • Select Deployment Target 대화상자에서 가상 기기를 선택하고 'OK'를 클릭합니다. Android 5(API 수준 21)에서도 작업이 실행되지만 OS 버전이 Android 10(API 수준 30) 이상인 기기에서 실행하는 것이 좋습니다.

홈 버튼을 길게 눌러 기기에서 어시스턴트 설정 및 확인 작업이 가능한지 확인합니다. 아직 로그인하지 않았다면 기기에서 어시스턴트에 로그인해야 합니다.

Android 가상 기기에 대한 자세한 내용은 가상 기기 만들기 및 관리를 참고하세요.

할 일 목록 샘플 앱을 보여주는 애니메이션

앱을 간단히 탐색하여 앱의 기능을 살펴봅니다. 더하기 아이콘을 탭하여 새 할 일 목록 항목을 만들고, 오른쪽 상단의 메뉴 항목을 탭하여 상태별로 할 일 항목을 검색하고 필터링합니다.

Play Console에 업로드

Google Play Console 프로젝트로의 앱 업로드는 Android 스튜디오에서 앱 작업 테스트 도구를 사용하기 위한 필수 작업입니다. Android 스튜디오에서 앱을 빌드하고 내부 버전 초안으로 Play Console에 업로드합니다.

Android 스튜디오에서 앱을 빌드하려면 다음 단계를 따르세요.

  1. Build > Generate Signed Bundle / APK로 이동합니다.
  2. 'Android App Bundle'을 선택하고 Next를 클릭합니다.
  3. sign your app에 세부정보를 입력하고 Next를 클릭합니다.
  4. 'prodRelease' 빌드 변형을 선택하고 Finish를 클릭합니다.

Google Play Console에서 방금 만든 App Bundle을 새로운 앱으로 업로드합니다.

  1. All apps 페이지에서 Create app을 클릭합니다.
  2. 앱에 원하는 이름을 지정하고 Create app을 클릭합니다. 이 Codelab에서는 앱을 만든 후 앱 정보를 입력할 필요가 없습니다.
  3. 사이드바 메뉴에서 Testing으로 이동하여 Internal testing 페이지를 찾습니다.
  4. Internal testing 페이지에서 Create new release를 클릭합니다.
  5. Continue를 클릭하여 Google Play 앱 서명에 동의합니다.
  6. App bundles and APKs 패널에서 이전에 생성한 AAB 파일을 업로드합니다(app/prod/release 디렉터리에 있을 가능성이 높음). Save를 클릭합니다.

테스트 플러그인 설치

앱 작업 테스트 도구 플러그인을 사용하면 테스트 기기에서 단일 사용자를 위한 앱 작업 테스트를 진행할 수 있습니다. 아직 테스트 도구가 없다면 다음 단계에 따라 설치하세요.

  1. File > Settings(MacOS의 경우 Android Studio > Preferences)로 이동합니다.
  2. 플러그인 섹션에서 'Marketplace'로 이동하여 'App Actions test tool'을 검색합니다. 수동으로 테스트 도구를 다운로드하여 설치할 수도 있습니다.
  3. 도구를 설치하고 Android 스튜디오를 다시 시작합니다.

이 단계에서는 앱 열기 기능 BII를 구현하여 사용자가 어시스턴트를 사용하여 진행 중 및 완료된 작업을 확인할 수 있도록 합니다. 이렇게 하려면 actions.xml에서 BII를 정의하여 작업 필터링 기능을 위한 기존 딥 링크를 어시스턴트로 확장해야 합니다. 기기에서 작업을 테스트하여 이 섹션을 완료합니다.

BII를 구현하기 전에 앱의 기존 딥 링크가 식별된 앱 작업 동작을 충족하는지 확인합니다.

Android 디버그 브리지(adb) 명령줄 도구로 딥 링크를 테스트하려면 다음 단계를 따르세요.

  1. 기기에서 앱을 업데이트합니다.
  2. 앱 바 더보기 메뉴에 있는 새로고침 버튼을 탭하여 할 일 목록에 샘플 항목을 작성합니다.

할 일 목록 앱 툴바 더보기 메뉴

Google을 사용하여 열 수 있는 옵션이 표시되면 '항상'을 선택하여 Todo 앱에서 지원되는 링크를 열 수 있도록 합니다. 나중에 앱 설정에서 환경설정을 변경할 수 있습니다.

터미널에서 다음 adb 명령어를 각각 입력하여 앱의 작업 필터링 딥 링크를 테스트합니다.

진행 중인 할 일 보기

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/active-tasks"

완료된 할 일 보기

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/completed-tasks"

모든 할 일 보기

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/all-tasks"

위의 명령어는 앱의 목록 보기 기능을 열고 각 딥 링크의 뒤에 오는 경로에서 지정된 완료 상태를 기준으로 작업을 필터링하여 표시합니다.

BII 추가

actions.xml에서 이 링크를 열도록 구성된 앱 기능 열기 BII를 정의하여 작업 필터링 딥 링크를 Google 어시스턴트로 확장합니다.

다음 코드를 사용하여 app/src/main/res/xml 샘플 프로젝트 디렉터리에 있는 actions.xml을 업데이트하여 BII를 정의합니다.

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        //TODO: Handle intent parameters

        //TODO: Handle action fulfillment

    </action>
</actions>

인라인 인벤토리를 사용하여 인텐트 매개변수 처리

인텐트 매개변수는 사용자 쿼리에서 추출된 요소를 의미합니다. 예를 들어 사용자가 "Hey Google, ExampleApp에서 피자 주문해 줘"와 같이 말하면 어시스턴트는 '피자'를 food.item schema.org 인텐트로 추출하여 작업을 처리할 수 있도록 매개변수를 전달합니다.

앱 기능 열기 BII는 사용자 쿼리에서 추출된 앱 기능을 나타내는 하나의 매개변수인 feature를 지원합니다. 이 매개변수에는 인라인 인벤토리가 필요하며, 이를 통해 어시스턴트에 매개변수 값과 일치하는 지원되는 앱 기능 이름 모음을 제공합니다.

feature 인텐트 매개변수를 처리하려면 다음 코드를 사용하여 actions.xml을 업데이트해야 합니다.

actions.xml

<?xml version="1.0" encoding="utf-8"?>

<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        <parameter name="feature">
            <entity-set-reference entitySetId="FeatureEntitySet" />
        </parameter>

        //TODO: Handle action fulfillment

    </action>
</actions>

위의 샘플 코드를 사용하여 어시스턴트가 매개변수 태그에서 entity-set-reference로 정의된 인라인 인벤토리 FeatureEntitySet에 기능 매개변수 값을 일치시키도록 지시했습니다.

action 요소 아래 actions.xml에 다음 entity-set을 추가하여 BII를 위한 인라인 인벤토리를 정의합니다.

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action>
       ...
    </action>

    <entity-set entitySetId="FeatureEntitySet">
        <entity  url="https://todo.androidappactions.com/completed-tasks"
            name="completed tasks" alternateName="@array/completed_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/active-tasks"
            name="active tasks" alternateName="@array/active_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/all-tasks"
            name="all tasks" alternateName="@array/all_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/statistics"
            name="statistics" alternateName="@array/statistics_synonyms"/>
    </entity-set>
</actions>

위의 코드에서 네 개의 entity 요소가 포함된 entity-set 요소로 표시되는 인라인 인벤토리를 정의했습니다. 사용자가 요청을 통해 이 BII를 활성화하면 어시스턴트가 feature 매개변수 값을 entityname 속성과 일치시키고 일치하는 entityurl을 처리에 전달합니다.

예를 들어 사용자가 "Hey Google, ExampleApp에서 완료된 할 일 보여 줘"라고 말하면 어시스턴트는 feature 인텐트 매개변수 값인 '완료된 할 일'을 상응하는 인벤토리 entity와 연결합니다. 그런 다음 어시스턴트가 연결된 URL인 https://todo.androidappactions.com/completed-tasks을 처리로 전달합니다.

작업 처리 정의

이 작업을 실행하기 위해 어시스턴트가 전달한 URL을 처리하기 위해 fulfillmentactions.xml 요소를 정의합니다. 다음 코드를 사용하여 actionfulfillment를 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        ... //Parameter definition

        <fulfillment urlTemplate="{@url}"/>
        <fulfillment urlTemplate="https://todo.androidappactions.com/all-tasks"/>

    </action>
   ...
</actions>

위 샘플에서는 두 개의 fulfillment 요소를 정의했습니다. 첫 번째 방법은 feature 매개변수에서 생성된 딥 링크 어시스턴트를 트리거합니다. 이는 urlTemplate 속성에서 {@url} 자리표시자로 표시되어 있습니다. 두 번째 fulfillment는 할 일 보기를 여는 대체 요소로 feature 매개변수가 누락되었거나 일치하는 인라인 인벤토리 element를 찾을 수 없는 경우 필터링되지 않은 할 일 목록을 표시합니다.

앱 작업 테스트

개발 및 테스트 중에 테스트 기기에서 어시스턴트로 앱 작업을 미리보기 위해 앱 작업 테스트 도구를 사용합니다. 또한 도구를 사용하여 앱 작업의 인텐트 매개변수를 조정하고, 사용자가 어시스턴트에 실행을 요청하는 다양한 방식을 작업에서 어떻게 처리하는지 테스트할 수 있습니다.

다음 단계에 따라 테스트 도구로 앱 작업을 테스트하세요.

  1. 실제 Android 테스트 기기를 연결하거나 Android Emulator를 시작합니다.
  2. Tools > App Actions > App Actions Test Tool로 이동합니다. Android 스튜디오에 로그인하라는 메시지가 표시될 수 있습니다. Google Play Console에서 사용했던 것과 동일한 계정을 사용합니다.
  3. Invocation Name 입력란에 '할 일 목록'을 입력합니다.
  4. 어시스턴트의 언어가 'English (US)'가 아닌 경우 Locale 필드에 어시스턴트 언어와 일치하는 언어를 입력합니다.
  5. Create Preview를 클릭합니다.
  6. Configure 드롭다운 목록을 사용하여 actions.intent.OPEN_APP_FEATURE 인텐트를 선택합니다.
  7. feature 상자에서 기본 'History' 값을 '완료된 할 일'로 업데이트합니다.
  8. 'Run'을 클릭합니다.

또는 기기의 어시스턴트 앱에서 호출 이름을 직접 사용하여 앱 작업을 시도해 볼 수 있습니다. 예를 들어 "Hey Google, 할 일 목록에서 완료된 할 일 보여 줘"라고 말할 수 있습니다.

항목 검색 BII는 인앱 검색 기능을 Google 어시스턴트로 확장합니다. 이 단계에서는 항목 검색 BII를 구현하고 테스트하여 사용자가 샘플 앱에서 특정 할 일을 검색할 수 있도록 합니다.

샘플 앱에는 인앱 검색 기능을 위한 기존의 딥 링크가 있습니다. BII를 구현하기 전에 adb를 사용하여 이 딥 링크가 식별된 앱 작업 동작을 충족하는지 확인합니다.

다음 adb 명령어를 사용하여 검색 딥 링크를 테스트합니다.

# GET_THING deep link: in-app search
adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/search?q=milk"

위의 명령어는 검색어 '집'이 포함된 항목을 필터링하는 항목 목록 활동을 로드하는 딥 링크를 트리거합니다.

BII 추가

검색 관련 앱 작업 중에 어시스턴트는 사용자 쿼리의 검색어를 thing.name 인텐트 매개변수로 추출합니다. 그런 다음 어시스턴트는 fulfillment 요소에서 정의한 URL 템플릿에 매개변수를 매핑하여 처리를 위한 URL을 생성합니다.

앱에 항목 검색 BII를 정의하려면 actions.xml을 새로운 작업으로 업데이트해야 합니다.

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
   <action intentName="actions.intent.OPEN_APP_FEATURE">...</action>

   <action intentName="actions.intent.GET_THING">

        <parameter-mapping
                intentParameter="thing.name"
                urlParameter="q"/>

        <fulfillment urlTemplate="https://todo.androidappactions.com/search?q={q}">
        </fulfillment>

   </action>

   ...
</actions>

위 샘플에서 parameter-mapping 요소는 thing.name 인텐트 매개변수를 fulfillment 요소의 urlParameter 속성의 'q' 값에 할당합니다. 그런 다음, 어시스턴트는 딥 링크를 생성하여 urlParameter 값을 fulfillment urlTemplate의 '{q}' 자리표시자에 매핑합니다.

앱 작업 테스트

어시스턴트가 인앱 검색을 테스트하려면 다음 단계를 따르세요.

  1. 실제 Android 테스트 기기를 연결하거나 Android Emulator를 시작합니다.
  2. Tools > App Actions > App Actions Test Tool로 이동합니다.
  3. Update Preview를 클릭합니다.
  4. 'Configure' 드롭다운 목록을 사용하여 actions.intent.GET_THING 인텐트를 선택합니다. 'name' 값을 '운동화'에서 '우유'로 변경합니다.
  5. Run을 클릭합니다.

이 테스트에서 항목 검색 BII는 name 속성을 사용하여 앱에서 '집'이 포함된 할 일을 검색합니다. 이전 앱 작업과 마찬가지로 테스트 도구를 사용하여 작업을 테스트하거나 테스트 기기에서 "Hey Google, 할 일 목록에서 케이크 믹스 검색해 줘" 또는 다른 검색 구문을 사용하면 됩니다.

축하합니다

이제 일반 BII를 사용하여 거의 모든 Android 앱에서 Google 어시스턴트가 지원되도록 할 수 있게 되었습니다.

학습한 내용

이 Codelab에서 배운 내용은 다음과 같습니다.

  • 사용자가 어시스턴트를 사용하여 특정 앱 기능으로 바로 이동하게 하는 방법
  • 사용자가 어시스턴트가 인앱 검색에 액세스하게 하는 방법
  • 앱 작업 테스트 도구를 사용하여 일반 BII를 테스트하는 방법

다음 단계

여기에서 할 일 목록 앱을 더 조정해 볼 수 있습니다. 완료된 프로젝트를 살펴보려면 GitHub의 -마스터 분기 저장소를 참고하세요.

다음은 앱 작업으로 앱을 확장하는 방법을 더 알아볼 수 있는 몇 가지 제안사항입니다.

Actions on Google 과정을 계속 사용하려면 다음 리소스를 살펴보세요.

트위터에서 @ActionsOnGoogle을 팔로우하여 최신 소식을 확인하고 #AoGDevs로 트윗을 보내 내가 빌드한 결과물을 공유하세요.

의견 설문조사

마지막으로, 이 설문조사를 작성하여 이 Codelab 사용 경험에 관한 의견을 보내주세요.