Google 助理链接

您可以生成一个网址,该网址直接链接到您的 Action 的特定 intent。用户在网络浏览器或移动浏览器中点击 Google 助理链接(以前称为“操作链接”)会被定向到其设备上的 Google 助理,然后他们就可以直接与你的 Action 互动了。

Google 助理链接与目录网站链接不同,后者会将用户转到 Google 助理目录中的 Action 页面。

在下列情况下,Google 助理链接可以派上用场:

  • 将用户链接到方法指南网站上的语音指导说明。
  • 从帮助页面将用户关联到客户服务体验。
  • 将用户关联到更新 intent,以便他们选择加入您的未来更新。

在 Actions 控制台中,您可以从项目中生成 Google 助理链接。通过所有部署渠道(Alpha 版、Beta 版和正式版)提供 Google 助理链接。例如,如果您在 Action 的 Alpha 版中启用了 Google 助理链接,该链接将可供 Alpha 版测试人员使用。

如需为 Action 生成网址,请按以下步骤操作:

  1. Actions 控制台中,前往 Deploy > Assistant links
  2. 对于 Intent,选择要为其生成链接的 intent。
  3. 启用 Would you like to create links for intent_name? 选项。
  4. (可选)在广告系列参数部分中,输入您要在链接中额外捕获的任何信息作为网址参数。
  5. (可选)输入链接标题。使用此标题描述 Action 的用途。例如,如果您的 Action 会引导用户进入购买音乐会门票的交易流程,则链接标题可以是“购买音乐会门票”。

输入信息后,您可以查看和复制为 Google 助理链接生成的网址或代码段。在您想将用户定向到此特定 Action 的任何位置使用 Google 助理链接。

您可以通过模拟器或在设备上测试任何 intent(主 intent 或自定义 intent,无论是否带有参数)的 Google 助理链接。

如需在设备上测试 Google 助理关联,请按以下步骤操作:

  1. 在 Actions 控制台中生成 Google 助理链接
  2. 通过电子邮件、聊天消息或其他格式将 Google 助理链接作为网址发送给自己。
  3. 在内置 Google 助理的设备上,使用您创建 Actions 项目时所用的帐号登录 Google 助理。
  4. 在同一设备上,点击你发送给自己的 Google 助理链接。

确认 Google 助理链接按预期运行后,您需要重新部署您的 Action,以便用户能够使用该链接。

Google 助理链接可以选择在网址中包含 intent 和参数。使用广告系列参数部分添加广告系列参数。

如果 Google 助理链接不包含任何其他参数,Google 助理就会关联到您的 Action 的 MAIN intent (actions.intent.MAIN),其行为如下:

  • 如果您未在 Google 助理链接中明确启用 MAIN intent,Google 助理会匹配不含任何参数的主 intent,类似于“与 app_name 对话”的行为。
  • 如果你显式启用了 MAIN intent,Google 助理会将这些参数传递给你的 Action。

下面是一个使用了 MAIN intent 且不带其他参数的 Google 助理链接网址示例:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

Google 助理链接网址的一般语法如下:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

下表介绍了您可以设置的网址参数:

网址参数 说明
$action_id 操作的数字标识符。
$intent 内置 intent 或用户 intent 的全名。
$param Action 软件包中指定的 intent 参数的全名。
$value 在 Action 包中为 $param 声明的类型的网址编码值。
$utm_param 一个或多个 UTM 参数类型的列表。有效值包括:utm_sourceutm_mediumutm_campaignutm_termutm_content
$utm_value UTM 参数的字符串值。

如果 Google 助理链接包含内置 intent(该 intent 以 actions.intent. 开头),Google 助理会尝试提取网址中的所有内置 intent 参数,并将其传递给您的 Action。Google 助理不能理解为内置 intent 参数的所有参数都会被移除。

对于对话型 Action,Google 助理会将这些参数作为 AppRequest 消息的一部分发送到您的执行方式。

以下示例展示了如何指定一个 Google 助理链接网址,其中包含带有单个 intent 参数的内置 intent:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

对于用户 intent,Google 助理只会提取由您的 Action 作为 intent 的一部分定义的参数,并舍弃任何其他参数。

以下示例展示了如何指定包含用户 intent 的 Google 助理链接网址:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

对于上述示例网址,Google 助理会在 AppRequest 中添加 JSON 对象,如下所示:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

UTM 参数是用户点击 Google 助理链接后 Google 助理发送到您的 Action 的字符串。您稍后可以使用这些字符串中包含的信息进行分析。

Google 助理向您的 Action 发送的 UTM 参数包括:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

以下示例展示了如何指定包含 UTM 参数的 Google 助理链接网址:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

对于上面的示例网址,Google 助理会在 AppRequest 消息中添加以下参数:

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

借助丰富的 Google 助理链接,您可以使用 assis.js 让 Action 通过网站更容易被用户发现。用户可以试用您的 Action,并通过帐号关联将其 Google 帐号关联到您的服务。

当用户访问您的网站时,他们会看到“试用 Google 助理”按钮,该按钮会触发 Rich Assistant 关联流程。

为您的 Action 启用账号关联后,用户就可以在任何内置 Google 助理的设备上访问您的 Action。此外,用户可以将他们的帐号与您的服务相关联,以便获得更加个性化的体验。

当与账号关联搭配使用时,Rich Assistant 链接会使用您的授权网址,该网址是在 Actions 控制台中的项目中设置的。如需了解详情,请参阅帐号关联文档

前提条件

若要使用富媒体助理链接,您需要具备以下条件:

本地开发

如需在您的网站上添加 Google 助理富链接,请完成以下步骤:

  1. 在您的网页上添加以下 JavaScript 库,并将 <PROJECT_ID> 替换为您的 Actions 项目 ID:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. 将以下 HTML 标记添加到网页的某个位置。这将加载内嵌的“Try it with Google Assistant”按钮:

    <google-assistant-link-group>
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    

主动触发

如果您希望在用户首次访问您的网页时自动启动富媒体 Google 助理链接流程,请使用 <google-assistant-proactive-link> 标记。如果您应用此代码,在没有用户首次访问的情况下,链接也会激活,而无需用户选择内嵌按钮。

  1. id 添加到 Google 助理关联组代码:

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
  2. 在您的网页上放置 <google-assistant-proactive-action-link> 标记,并将其 groupId 属性设置为 id

    <google-assistant-link-group id="my-group">
      <!-- One or more <google-assistant-link> tags -->
      <google-assistant-link href="{ASSISTANT_LINK_1}">
      </google-assistant-link>
      <google-assistant-link href="{ASSISTANT_LINK_2}">
      </google-assistant-link>
    </google-assistant-link-group>
    
    <google-assistant-proactive-link
    groupId="my-group">
    </google-assistant-proactive-link>
    

Deployment

富媒体助理链接仅适用于您拥有的且已通过 Google 验证的网域。在本地开发时,您可以通过以下方法绕过此要求:能够访问 Actions 项目,登录您的 Google 帐号,并在脚本代码中设置 dev=true 查询参数。

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

如需部署包含 Google 助理富链接的 Action,请执行以下操作:

  1. 请在 Actions 控制台中的 Deploy > Brand Verification > Connect Site 下注册您的公共网域。
  2. 从脚本中移除 dev=true 查询参数:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
    </script>
    

限制和最佳做法

遵循以下限制和最佳做法,以便您的 Google 助理链接网址可以在目录或其他 Google 服务之外分发和引用:

  • 继续支持你使用的所有 Google 助理链接。如果您分发的 Google 助理链接稍后发生故障,您的 Actions 项目可能会被标记为运行状况不佳并被移除。
  • 发布链接意味着支持从不受信任的来源进行触发操作。对于任何关联的 Action,您必须先向用户明确确认,然后才能执行实际操作。例如,关闭智能家居设备的 Action 应该提示用户“确定要关闭 $applianceName 吗?”

    在这种情况下,实际操作是指会影响用户的服务、数据、设备、网络、计算机或 API 的任何操作。例如,发送电子邮件、执行交易、更改智能家居设备的状态、创建订阅或更新内容。