androidactions-on-googleapp-actions

What is the use of {@url} in actions.xml app action URL templates?


In my actions.xml file, I can provide inventory for my intent's parameters using <entity-set> tags. For each <entity>, the docs indicate that I can specify a value for either identifier or url. What's the difference between identifier and url? Why do I need a <parameter-mapping> tag if I use identifier, but not if I use url?


Solution

  • The key difference is that identifier values are URL-escaped. For example:

    <intent name="actions.intent.SOME_INTENT">
      <parameter name="param.name">
        <entity-set-reference entitySetId="identifier_entity_set">
      </parameter>
      <fulfillment urlTemplate="https://app.com/{param_value}">
        <parameter-mapping intentParameter="param.name" urlParameter="param_value" />
      </fulfillment>
    </intent>
    <entity-set entitySetId="identifier_entity_set">
      <entity identifier="escaped/url/path" name="hi">
    </entity-set>
    

    If the user says "hi" for param.name, the resolved urlTemplate will be: https://app.com/escaped%2Furl%2Fpath.

    <intent name="actions.intent.SOME_INTENT">
      <parameter name="param.name">
        <entity-set-reference entitySetId="url_entity_set">
      </parameter>
    </intent>
      <fulfillment urlTemplate="{@url}" />
    <entity-set entitySetId="url_entity_set">
      <entity url="https://app.com/not/esacaped/url/path" name="bye">
    </entity-set>
    

    If the user says "bye" for param.name, the resolved urlTemplate will be: https://app.com/not/esacaped/url/path.

    Also, note that if you have {@url} in your urlTemplate, you shouldn't include a <parameter-mapping> for it; it's assumed that you have exactly one <entity-set> with url values.