如何为音乐播放器App接入Google Voice Assistant？已试UAMP无效

一、基础配置检查（解决UAMP示例失效的核心前提） #

• 设备要求：搭载Android 8.0及以上系统，登录与App签名一致的Google账号，将Google Assistant设置为默认语音助手。
• 签名验证：必须使用正式签名密钥打包安装App，Debug签名的应用无法被Google Assistant识别（这是UAMP示例大概率失效的原因）。
• 权限确认：确保App已获取POST_NOTIFICATIONS（Android 13+）、INTERNET、ACCESS_NETWORK_STATE权限，以及媒体访问权限READ_MEDIA_AUDIO（Android 13+）或READ_EXTERNAL_STORAGE（旧版本）。

二、实现MediaSession核心交互逻辑 #

Google Assistant依赖MediaSession与App进行播放指令交互，这是核心实现点：

• 创建MediaSessionCompat实例，并重写关键回调方法处理播放请求：

  val mediaSession = MediaSessionCompat(context, "MusicPlayerSession")
  mediaSession.setCallback(object : MediaSessionCompat.Callback() {
      override fun onPlay() {
          // 执行播放逻辑
      }
      override fun onPlayFromMediaId(mediaId: String?, extras: Bundle?) {
          // 根据mediaId播放指定歌曲
      }
      override fun onPlayFromSearch(query: String?, extras: Bundle?) {
          // 根据搜索关键词匹配并播放歌曲
      }
  })
  mediaSession.isActive = true
  

• 将MediaSession与MediaController绑定，确保通知栏媒体控件与Session联动，让Assistant能实时感知播放状态。

三、配置App Actions实现指令匹配 #

• 在res/xml目录下创建actions.xml，定义媒体播放相关的内置意图：

  <actions>
      <action intentName="actions.intent.PLAY_MEDIA">
          <fulfillment urlTemplate="app://play/{query}">
              <parameter-mapping
                  intentParameter="media.name"
                  urlParameter="query" />
          </fulfillment>
          <parameter name="media.name" />
          <parameter name="media.artist" />
          <parameter name="media.genre" />
          <metadata name="android.app.searchable" resource="@xml/searchable" />
      </action>
  </actions>
  

• 在AndroidManifest.xml中声明App Actions配置，关联媒体服务：

  <application ...>
      <activity ...>
          <intent-filter>
              <action android:name="android.intent.action.MAIN" />
              <category android:name="android.intent.category.LAUNCHER" />
          </intent-filter>
          <meta-data
              android:name="android.app.actions"
              android:resource="@xml/actions" />
      </activity>
      <service
          android:name=".MusicService"
          android:foregroundServiceType="mediaPlayback">
          <intent-filter>
              <action android:name="android.media.browse.MediaBrowserService" />
          </intent-filter>
      </service>
  </application>
  

四、测试与验证 #

• 语音指令测试：直接说出“在[你的App名称]中播放[歌曲名]”，注意App名称需与Manifest中android:label完全一致。
• 工具验证：使用Android Studio的App Actions Test Tool（路径：Tools > App Actions > Test Tool）模拟意图调用，检查参数传递是否正常。
• 日志排查：在Logcat中过滤MediaSession或Assistant关键词，定位指令无响应时的错误原因（如权限缺失、Session未激活等）。

五、常见问题排查 #

• UAMP示例失效：优先检查是否使用正式签名打包，以及设备是否登录了匹配的Google账号。
• 指令无响应：确认actions.xml中的意图名称、参数映射无误，且MediaSession处于活跃状态（isActive = true）。
• App无法被匹配：确保语音指令中的App名称与Manifest的android:label一致，或在App Actions配置中添加别名参数。

内容的提问来源于stack exchange，提问作者Dipti Agravat