앱 MVP Google Assistant App Actions: 기능 선택·진입 경로·테스트를 나누는 5가지 기준
사용자가 음성으로 바로 시작할 ‘한 가지 작업’이 있을 때만 검토합니다
App Actions는 Android 앱의 기능을 Google Assistant가 이해할 수 있는 작업 단위로 연결하는 방식입니다. 그러나 앱에 음성 입력이 있다는 이유만으로 붙이는 기능은 아닙니다. 사용자가 앱 이름과 함께 요청했을 때 바로 열어도 맥락이 분명한 기능인지, 필요한 값을 안전하게 받아 화면을 열 수 있는지, 그리고 목적지에서 사용자가 다음 행동을 계속할 수 있는지를 따로 확인해야 합니다.
예를 들어 운동 기록 앱의 ‘운동 시작’, 할 일 앱의 ‘항목 찾기’, 예약 앱의 특정 기능 열기처럼 요청과 목적지가 짧게 연결되는 흐름은 후보가 될 수 있습니다. 반면 결제 확정, 민감정보 수정, 여러 화면을 거쳐야 의미가 생기는 복잡한 업무는 음성 진입 하나로 완료를 약속하기보다 앱 안의 확인 흐름을 남겨야 합니다. App Actions를 추가했다고 Assistant가 모든 요청에서 앱을 노출하거나 사용자가 작업을 끝낸다고 볼 수는 없습니다.
먼저 분리할 5가지 결정
1. 사용자 작업: 사용자가 말로 시작해도 의미가 같은 한 가지 기능인가.
2. BII 적합성: 해당 작업에 맞는 built-in intent가 있는가. 단순히 비슷한 이름의 BII를 고르지 않았는가.
3. 파라미터와 폴백: 요청에서 받은 검색어·대상·유형이 무엇이며, 값이 없거나 해석하지 못했을 때 어느 화면으로 갈 것인가.
4. 진입 경로: 명시적 Activity와 deep link 중 현재 앱의 탐색·로그인·복귀 흐름에 맞는 방식은 무엇인가.
5. 검증 신호: preview 생성, BII 실행, 목적지 표시, 오류·로그인·미설치 상황 관찰을 하나의 ‘출시 성공’으로 합치지 않았는가.
Android 공식 문서에서 App Actions는 `shortcuts.xml`의 `capability`로 BII와 앱의 fulfilment를 연결합니다. fulfilment는 Assistant가 앱을 열 때 만드는 Android intent 또는 deep link의 모양을 정합니다. 즉, 음성 문장을 앱 화면에 붙이는 작업보다 ‘어떤 입력을 어떤 목적지에 넘길지’ 계약을 만드는 작업에 가깝습니다.
BII는 기능 이름이 아니라 사용자의 요청 형태에 맞춥니다
App Actions의 BII는 사용자가 자주 말하는 작업의 의미를 모델링합니다. 일반적인 앱 기능에는 `OPEN_APP_FEATURE`, 앱 안 검색에는 `GET_THING` 같은 공통 BII를 검토할 수 있고, 업종에 맞는 BII도 있습니다. 선택의 출발점은 ‘우리 기능 이름’이 아니라 사용자가 실제로 무엇을 요청하고, 앱이 어느 결과까지 책임질 수 있는가입니다.
| MVP 상황 | 먼저 확인할 질문 | 초기에 피할 판단 |
|---|---|---|
| 콘텐츠·상품·할 일 검색 | 검색어가 없어도 보여 줄 기본 결과가 있는가 | 검색 결과가 없는 상태를 성공으로 기록 |
| 특정 화면 열기 | 음성으로 말해도 같은 화면 목적이 유지되는가 | 여러 기능을 한 capability에 묶기 |
| 카테고리별 실행 기능 | BII의 필수·권장 파라미터를 처리할 수 있는가 | 앱 기능과 무관한 BII 선언 |
| 로그인 필요 기능 | 로그인 전후의 복귀 위치가 안전한가 | 로그인 후 홈으로만 보내고 원래 요청을 잃기 |
| 민감하거나 되돌리기 어려운 행동 | 앱 안에서 명시적 확인을 요구하는가 | 음성 진입만으로 확정 처리 |
App Actions를 먼저 도입할지 판단하려면 ‘기능이 있는가’보다 ‘짧은 한 문장으로 요청한 뒤 정확한 목적지와 다음 행동이 자연스러운가’를 검토하세요. 지원되는 BII·파라미터·언어는 변경될 수 있으므로 구현 시점에는 현재 Android Developers BII reference를 다시 확인해야 합니다.
앱 링크의 도메인 검증·앱 열기·웹 폴백 기준을 정리했다면, App Actions에서는 그 링크가 음성 요청의 fulfilment로 안전하게 쓰이는지도 별도로 확인하세요. App Links 검증과 Assistant 요청의 의미 매핑은 다른 문제입니다.
파라미터는 전달 성공과 기능 완료를 분리해 설계합니다
한 capability에는 하나 이상의 fulfilment를 둘 수 있습니다. 앱이 처리 가능한 값이 포함된 요청과 값이 없는 요청에 서로 다른 fulfilment를 선언할 수도 있습니다. 예를 들어 검색어가 있을 때는 해당 검색 결과로, 검색어가 없을 때는 검색 입력 화면이나 기본 탐색 화면으로 보내는 식입니다.
여기서 가장 중요한 점은 intent extra 또는 URL query가 도착했다는 사실이 사용자의 요청이 완료됐다는 뜻은 아니라는 것입니다. 앱은 그 값을 형식·권한·현재 로그인 상태에 맞게 확인하고, 값을 사용할 수 없으면 이해 가능한 대안을 보여야 합니다. 파라미터를 URL에 넣는다면 로그·공유 화면·분석 도구에 노출되어도 되는 값인지도 검토하세요. 비밀번호, 결제정보, 접근 토큰처럼 민감한 값을 deep link query로 다루는 방식은 피해야 합니다.
목적지 체크리스트
BII 이름과 앱 안 기능의 사용자 목적이 일치하는가.
처리할 파라미터와 값이 없는 경우의 화면을 각각 정했는가.
명시적 Activity 또는 deep link가 로그인·권한·앱 복귀 뒤에도 안전한가.
잘못된 값, 오래된 링크, 기능 제거 뒤의 대체 화면이 있는가.
요청 수신, 목적지 표시, 실제 사용자 행동을 별도 이벤트·QA 기록으로 남기는가.
우리 앱 MVP의 음성 진입 기능과 목적지 조건 점검하기
명시적 Activity와 deep link는 현재 탐색 구조로 고릅니다
Android 문서는 fulfilment가 명시적 Activity를 열거나 deep link URL을 사용할 수 있다고 안내합니다. 이미 앱이 deep link 중심의 탐색을 갖췄다면 동일한 경로를 활용할 수 있습니다. 다만 웹 URL이 존재한다는 사실만으로 음성 진입에 적합한 것은 아닙니다. 앱 미설치, 로그인 필요, 특정 콘텐츠가 사라진 경우, 잘못된 파라미터가 들어온 경우에 각각 사용자가 어디로 가는지 확인해야 합니다.
명시적 Activity도 단순한 정답은 아닙니다. Assistant가 외부에서 시작한 intent로 Activity를 열 수 있어야 하며, 앱이 재생성되거나 백스택이 달라졌을 때도 목적지를 재현해야 합니다. 구현 방법을 결정한 뒤에는 ‘음성 요청 → 앱 시작 → 목적지 → 사용자가 가능한 다음 행동’ 전체를 한 번의 테스트 케이스로 남기되, 각 단계의 관찰값은 분리해 기록하는 편이 좋습니다.
테스트는 preview와 실제 노출을 같은 증거로 보지 않습니다
개발 중에는 Android Studio의 Google Assistant plugin으로 preview를 만들고 선택한 BII를 테스트할 수 있습니다. 이 테스트는 capability·파라미터·목적지 처리의 문제를 찾는 데 유용합니다. 하지만 preview가 만들어졌다는 사실은 모든 사용자 요청에서 앱이 노출된다는 보증이 아닙니다. 공식 문서도 App Actions의 트리거가 품질과 관련성 등 여러 요인의 영향을 받고 Google이 노출 여부를 재량으로 판단할 수 있다고 설명합니다.
따라서 출시 기록에는 다음처럼 사실을 나눠 적으세요. ‘preview 생성됨’, ‘특정 기기·계정·언어에서 BII 테스트 실행됨’, ‘파라미터가 목적지에 도착함’, ‘로그인 후 요청 맥락이 유지됨’, ‘사용자가 실제 작업을 완료함’은 서로 다른 증거입니다. 마지막 항목을 측정할 때도 개인정보 처리방침과 동의 범위 밖의 추적을 추가하지 않도록 주의해야 합니다.
자주 묻는 질문
App Actions를 넣으면 Google Assistant가 우리 앱을 항상 열어 주나요?
아닙니다. App Actions는 capability와 BII를 통해 앱 기능을 연결하는 방법입니다. 공식 문서는 노출이 품질·관련성 등 여러 요소의 영향을 받으며 Google이 재량을 행사할 수 있다고 안내합니다. 따라서 항상 노출된다고 약속하거나 KPI로 단정하지 말고, 앱 안 목적지와 대체 흐름을 먼저 검증하세요.
BII에 맞는 파라미터를 모두 처리해야 하나요?
앱이 처리할 수 있는 파라미터와 값이 없을 때의 fulfilment를 명확히 정하는 것이 중요합니다. Android 문서는 capability에 여러 fulfilment를 둘 수 있고, 선언된 파라미터에 따라 적절한 fulfilment가 선택될 수 있다고 설명합니다. 현재 BII reference의 필수·권장 항목을 구현 시점에 확인하세요.
deep link로 구현하면 App Links 검증도 끝난 것인가요?
아닙니다. App Actions fulfilment에서 deep link를 쓰는 문제와 Android App Links의 도메인 연결·검증은 별도입니다. 설치·로그인·잘못된 값·앱 미설치 같은 흐름까지 테스트한 뒤 각각의 상태를 기록하세요.
preview가 통과했는데 실제 음성 요청에서 테스트를 계속해야 하나요?
네. preview는 개발 중 capability와 목적지 처리를 확인하는 증거입니다. 실제 기기·지원 언어·계정·앱 상태에서 요청이 어떻게 처리되는지는 별도로 관찰해야 하며, 관찰하지 않은 노출·완료를 추정하면 안 됩니다.
출시 전 결론: 기능·BII·목적지·테스트 증거를 따로 남기세요
App Actions는 앱의 모든 기능을 음성으로 바꾸는 작업이 아니라, 사용자가 바로 시작해도 의미가 분명한 한 가지 작업을 Assistant와 연결하는 선택입니다. 기능 적합성, BII와 파라미터, Activity·deep link의 목적지, 로그인·오류 폴백, preview와 실제 기기 관찰을 분리하면 범위를 과장하지 않고도 MVP의 진입 경험을 검증할 수 있습니다.