어시스턴트 링크

작업의 특정 인텐트에 직접 연결되는 URL을 생성할 수 있습니다. 사용자가 웹브라우저나 모바일 브라우저에서 어시스턴트 링크 (이전 명칭: 작업 링크)를 클릭하면 기기의 어시스턴트로 이동하여 작업과 직접 상호작용합니다.

어시스턴트 링크는 어시스턴트 디렉터리의 작업 페이지로 사용자를 보내는 디렉터리 웹 링크와 다릅니다.

다음과 같은 상황에서 어시스턴트 링크를 유용하게 사용할 수 있습니다.

  • 방법 안내 웹사이트의 음성 안내 도움말로 사용자를 연결합니다.
  • 사용자를 도움말 페이지의 고객 지원 환경으로 연결합니다.
  • 사용자가 향후 업데이트에 동의할 수 있도록 사용자를 업데이트 인텐트에 연결합니다.

Actions 콘솔의 프로젝트 내에서 어시스턴트 링크를 생성할 수 있습니다. 어시스턴트 링크는 모든 배포 채널 (알파, 베타, 프로덕션)을 통해 사용할 수 있습니다. 예를 들어 작업의 알파 버전에서 어시스턴트 링크가 사용 설정된 경우 알파 테스터가 링크를 사용할 수 있습니다.

작업의 URL을 생성하려면 다음 단계를 따르세요.

  1. Actions 콘솔에서 배포 > 어시스턴트 링크로 이동합니다.
  2. 인텐트에서 링크를 생성하려는 인텐트를 선택합니다.
  3. intent_name의 연결을 사용 설정하시겠어요? 옵션을 사용 설정합니다.
  4. (선택사항) 캠페인 매개변수 섹션에서 링크에 추가로 캡처할 정보를 URL 매개변수로 입력합니다.
  5. (선택사항) 링크 제목을 입력합니다. 이 제목을 사용하여 작업의 기능을 설명합니다. 예를 들어 작업에서 사용자가 콘서트 티켓을 구매하기 위해 거래 흐름을 중단하는 경우 링크 제목은 '콘서트 티켓 구매'일 수 있습니다.

정보를 입력한 후에는 생성된 URL 또는 어시스턴트 링크의 생성된 코드 스니펫을 확인하고 복사할 수 있습니다. 사용자를 이 특정 작업으로 안내하려면 어디든 어시스턴트 링크를 사용하세요.

시뮬레이터 또는 기기에서 모든 인텐트 (기본 또는 맞춤, 매개변수 유무와 관계없음)의 어시스턴트 링크를 테스트할 수 있습니다.

기기에서 어시스턴트 링크를 테스트하려면 다음 단계를 따르세요.

  1. Actions 콘솔에서 어시스턴트 링크를 생성합니다.
  2. 어시스턴트 링크를 이메일, 채팅 메시지 또는 기타 형식으로 나에게 URL로 전송합니다.
  3. 어시스턴트 지원 기기에서 작업 프로젝트를 만들 때 사용한 것과 동일한 계정으로 어시스턴트에 로그인합니다.
  4. 같은 기기에서 나에게 보낸 어시스턴트 링크를 클릭합니다.

어시스턴트 링크가 예상대로 작동하는지 확인한 후 작업을 다시 배포하여 사용자에게 링크를 제공해야 합니다.

어시스턴트 링크는 선택적으로 URL에 인텐트와 매개변수를 포함할 수 있습니다. 캠페인 매개변수 섹션을 사용하여 캠페인 매개변수를 추가합니다.

어시스턴트 링크에 추가 매개변수가 없으면 Google 어시스턴트는 다음 동작으로 작업의 MAIN 인텐트 (actions.intent.MAIN)에 연결합니다.

  • 어시스턴트 링크에서 MAIN 인텐트를 명시적으로 사용 설정하지 않았다면 어시스턴트는 'app_name에 연결' 동작과 유사하게 매개변수 없이 기본 인텐트를 일치시킵니다.
  • MAIN 인텐트를 명시적으로 사용 설정한 경우 어시스턴트는 매개변수를 작업에 전달합니다.

다음은 추가 매개변수 없이 MAIN 인텐트를 사용하는 어시스턴트 링크 URL의 예입니다.

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

어시스턴트 링크 URL의 일반적인 문법은 다음과 같습니다.

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

설정할 수 있는 URL 매개변수는 다음 표에 설명되어 있습니다.

URL 매개변수 설명
$action_id 작업의 숫자 식별자입니다.
$intent 내장 또는 사용자 인텐트의 전체 이름입니다.
$param 작업 패키지에 지정된 인텐트 매개변수의 전체 이름입니다.
$value 작업 패키지의 $param에 대해 선언된 유형의 URL 인코딩 값입니다.
$utm_param 하나 이상의 UTM 매개변수 유형의 목록입니다. 유효한 값은 utm_source, utm_medium, utm_campaign, utm_term, utm_content입니다.
$utm_value UTM 매개변수의 문자열 값입니다.

어시스턴트 링크에 내장 인텐트가 포함되어 있으면 (인텐트가 actions.intent.로 시작함) Google 어시스턴트는 URL에서 내장 인텐트 매개변수를 추출하려고 시도하여 작업에 전달합니다. 어시스턴트가 내장 인텐트 매개변수로 이해하지 못하는 매개변수는 모두 삭제됩니다.

대화형 작업의 경우 어시스턴트는 AppRequest 메시지의 일부로 이러한 매개변수를 처리에 전송합니다.

다음 예는 인텐트 매개변수가 하나인 내장 인텐트가 포함된 어시스턴트 링크 URL을 지정하는 방법을 보여줍니다.

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

사용자 인텐트의 경우 Google 어시스턴트는 작업이 인텐트의 일부로 정의한 매개변수만 추출하고 다른 매개변수는 모두 삭제합니다.

다음 예는 사용자 인텐트가 포함된 어시스턴트 링크 URL을 지정하는 방법을 보여줍니다.

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

위 URL 예의 경우 AppRequest에서 어시스턴트는 다음과 같이 JSON 객체를 추가합니다.

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

UTM 매개변수는 사용자가 어시스턴트 링크를 클릭할 때 Google 어시스턴트가 작업에 전송하는 문자열입니다. 이 문자열에 포함된 정보는 나중에 분석에 사용할 수 있습니다.

어시스턴트가 작업에 전송하는 UTM 매개변수는 다음과 같습니다.

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

다음 예는 UTM 매개변수가 포함된 어시스턴트 링크 URL을 지정하는 방법을 보여줍니다.

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

위의 URL 예에서 어시스턴트는 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',
}

리치 어시스턴트 링크를 사용하면 help.js를 사용하여 웹사이트를 통해 작업의 검색 가능성을 높일 수 있습니다. 사용자는 작업을 사용해 볼 수 있을 뿐 아니라 계정 연결을 사용하여 Google 계정을 서비스에 연결할 수도 있습니다.

사용자가 웹사이트를 방문하면 리치 어시스턴트 링크 흐름을 트리거하는 'Google 어시스턴트로 사용해 보기' 버튼이 표시됩니다.

작업에 계정 연결을 사용 설정하면 사용자가 어시스턴트 지원 기기에서 작업에 액세스할 수 있습니다. 또한 사용자는 자신의 계정을 Google 계정에 서비스와 연결하여 더 맞춤화된 환경을 이용할 수 있습니다.

계정 연결과 함께 사용할 경우 Rich Assistant 링크는 Actions 콘솔의 프로젝트에 설정된 승인 URL을 사용합니다. 자세한 내용은 계정 연결 문서를 참고하세요.

기본 요건

리치 어시스턴트 링크를 사용하려면 다음이 필요합니다.

로컬 개발

웹사이트에 풍부한 어시스턴트 링크를 포함하려면 다음 단계를 완료하세요.

  1. 페이지에 다음 JavaScript 라이브러리를 포함하여 <PROJECT_ID>를 작업 프로젝트 ID로 바꿉니다.

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. 다음 HTML 태그를 페이지 어딘가에 추가합니다. 이렇게 하면 인라인 'Google 어시스턴트로 사용해 보기' 버튼이 로드됩니다.

    <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-assistant-proactive-link> 태그를 사용하세요. 이 태그를 적용하면 처음 방문 시 사용자가 인라인 버튼을 선택하지 않아도 링크가 활성화됩니다.

  1. 어시스턴트 연결 그룹 태그에 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>
    
  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을 통해 인증한 도메인에서만 작동합니다. 로컬에서 개발하는 경우 작업 프로젝트에 액세스하고 Google 계정에 로그인한 후 스크립트 태그에 dev=true 쿼리 매개변수를 설정하면 이 요구사항을 우회할 수 있습니다.

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

다양한 어시스턴트 링크로 작업을 배포하려면 다음 안내를 따르세요.

  1. 배포 > 브랜드 인증 > 사이트 연결에서 Actions 콘솔의 공개 도메인을 등록합니다.
  2. 스크립트에서 dev=true 쿼리 매개변수를 삭제합니다.

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

제한사항 및 권장사항

어시스턴트 링크 URL을 디렉터리나 다른 Google 서비스 외부에 배포하고 참조할 수 있도록 다음 제한사항 및 권장사항이 적용됩니다.

  • 모든 어시스턴트 링크를 계속 지원합니다. 어시스턴트 링크를 배포하다가 나중에 중단되면 작업 프로젝트가 비정상으로 신고되어 게시 중단될 수 있습니다.
  • 링크를 게시하면 신뢰할 수 없는 소스에서 트리거할 수 있습니다. 연결된 작업의 경우 실제 작업을 실행하기 전에 사용자에게 명시적으로 확인해야 합니다. 예를 들어 스마트 홈 어플라이언스를 끄는 작업은 사용자에게 '$applianceName를 끄시겠습니까?'라는 메시지를 표시해야 합니다.

    이 문맥에서 실제 작업은 사용자의 서비스, 데이터, 기기, 네트워크, 컴퓨터, API에 영향을 미치는 모든 작업입니다. 예를 들어 이메일 전송, 거래 실행, 스마트 홈 어플라이언스의 상태 변경, 구독 생성, 콘텐츠 업데이트 등이 있습니다.