کنش‌های مکالمه در 13 ژوئن 2023 منسوخ شد. برای اطلاعات بیشتر، غروب کنش‌های مکالمه را ببینید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پیوندهای دستیار

می‌توانید یک URL ایجاد کنید که مستقیماً به یک هدف خاص از Action شما پیوند دارد. کاربرانی که روی پیوند Assistant (که قبلاً پیوندهای Action نامیده می‌شد) در مرورگر وب یا تلفن همراه کلیک می‌کنند، به Assistant در دستگاه خود هدایت می‌شوند، جایی که مستقیماً با Action شما تعامل دارند.

پیوندهای دستیار با پیوندهای وب دایرکتوری متفاوت است، که کاربر را به صفحه Action شما در فهرست راهنمای Assistant می فرستد.

در اینجا مواردی وجود دارد که پیوندهای دستیار می توانند مفید باشند:

پیوند دادن کاربران به دستورالعمل‌های صوتی از یک وب‌سایت چگونه.
پیوند دادن کاربران به تجربه پشتیبانی مشتری از صفحه راهنما.
پیوند دادن کاربران به یک هدف به‌روزرسانی تا بتوانند در به‌روزرسانی‌های آینده شما شرکت کنند.

یک پیوند دستیار ایجاد کنید

می توانید پیوندهای Assistant را از داخل پروژه خود در کنسول Actions ایجاد کنید. پیوندهای دستیار از طریق همه کانال‌های استقرار (آلفا، بتا و تولید) در دسترس هستند. به عنوان مثال، اگر پیوند دستیار شما در نسخه آلفای Action شما فعال باشد، پیوند برای آزمایش‌کنندگان آلفا در دسترس است.

برای ایجاد URL برای یک Action، این مراحل را دنبال کنید:

در کنسول Actions ، به Deploy > Assistant links بروید.
برای Intent ، هدفی را که می‌خواهید پیوندی برای آن ایجاد کنید، انتخاب کنید.
آیا می خواهید پیوند برای intent_name را فعال کنید؟ گزینه
(اختیاری) در بخش پارامترهای کمپین ، اطلاعاتی را که می‌خواهید به عنوان پارامترهای URL در پیوند اضافه کنید، وارد کنید.
(اختیاری) عنوان پیوند را وارد کنید. از این عنوان برای توصیف آنچه که Action انجام می دهد استفاده کنید. به عنوان مثال، اگر Action شما باعث کاهش جریان تراکنش برای خرید بلیط کنسرت شود، عنوان پیوند شما می تواند «خرید بلیط کنسرت» باشد.

پس از وارد کردن اطلاعات خود، می توانید URL تولید شده یا قطعه کد تولید شده را برای پیوند دستیار مشاهده و کپی کنید. از پیوند Assistant در هر کجا که می خواهید کاربران را به این Action خاص هدایت کنید استفاده کنید.

پیوندهای دستیار تست

می‌توانید پیوندهای دستیار را برای هر هدفی (اصلی یا سفارشی، با یا بدون پارامتر) از طریق شبیه‌ساز یا روی یک دستگاه آزمایش کنید.

برای آزمایش پیوند دستیار خود در دستگاه، این مراحل را دنبال کنید:

پیوند Assistant را در کنسول Actions ایجاد کنید .
پیوند دستیار را به عنوان URL در ایمیل، پیام چت یا فرمت های دیگر برای خود ارسال کنید.
در دستگاهی که دارای Assistant فعال است، با همان حسابی که برای ایجاد پروژه Actions خود استفاده کردید، به Assistant وارد شوید.
در همان دستگاه، روی پیوند Assistant که برای خود ارسال کردید، کلیک کنید.

هنگامی که عملکرد پیوند دستیار را همانطور که انتظار می رود تأیید کردید، باید Action خود را مجدداً اجرا کنید تا پیوند در دسترس کاربران خود قرار گیرد.

پارامترهای پیوند دستیار

پیوندهای دستیار می توانند به صورت اختیاری حاوی یک هدف و پارامترها در URL باشند. از بخش پارامترهای کمپین برای اضافه کردن پارامترهای کمپین استفاده کنید.

وقتی پیوند دستیار فاقد پارامترهای اضافی باشد، دستیار Google با رفتار زیر به هدف MAIN ( actions.intent.MAIN ) Action شما پیوند می‌دهد:

اگر به صراحت هدف MAIN را در پیوند دستیار فعال نکرده باشید، دستیار بدون هیچ پارامتری با هدف اصلی مطابقت دارد، مشابه رفتار «Talk to app_name».
اگر صراحتاً هدف MAIN را فعال کرده باشید، Assistant پارامترها را به Actions شما ارسال می‌کند.

در اینجا نمونه‌ای از URL پیوند Assistant با استفاده از هدف MAIN بدون پارامترهای اضافی آورده شده است:

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

مشخصات URL پیوند دستیار

نحو کلی برای URL یک پیوند Assistant به شرح زیر است:

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

پارامترهای URL که می توانید تنظیم کنید در جدول زیر توضیح داده شده است:

پارامتر URL	توضیحات
`$action_id`	شناسه عددی Action.
`$intent`	نام کامل یک هدف داخلی یا کاربر.
`$param`	نام کامل یک پارامتر intent مشخص شده در بسته Action.
`$value`	مقدار کدگذاری شده URL از نوع اعلام شده برای `$param` در بسته Action.
`$utm_param`	فهرست یک یا چند نوع پارامتر UTM. مقادیر معتبر عبارتند از: `utm_source` ، `utm_medium` ، `utm_campaign` ، `utm_term` ، و `utm_content` .
`$utm_value`	مقدار رشته پارامتر UTM.

آدرس‌های اینترنتی پیوند دستیار با اهداف داخلی

اگر پیوند دستیار حاوی یک intent داخلی باشد (اینتنت با actions.intent. شروع می‌شود)، دستیار Google سعی می‌کند هر پارامتر هدف داخلی را در URL استخراج کرده و به Action شما ارسال کند. هر پارامتری که Assistant به عنوان پارامترهای intent داخلی درک نمی‌کند، حذف می‌شود.

برای اقدامات مکالمه، دستیار این پارامترها را به عنوان بخشی از پیام AppRequest به انجام شما ارسال می کند.

مثال زیر نشان می‌دهد که چگونه می‌توانید URL پیوند Assistant را که شامل یک intent داخلی با یک پارامتر intent باشد مشخص کنید:

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

URL های دستیار را با اهداف کاربر پیوند می دهد

برای اهداف کاربر، دستیار Google فقط پارامترهایی را استخراج می‌کند که توسط Action شما به عنوان بخشی از هدف تعریف شده‌اند و سایر پارامترها را نادیده می‌گیرند.

مثال زیر نشان می‌دهد که چگونه می‌توانید URL پیوند دستیار را مشخص کنید که شامل یک هدف کاربر است:

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

برای URL مثال بالا، در AppRequest ، Assistant یک شی JSON را به صورت زیر اضافه می کند:

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

URLهای پیوند دستیار با پارامترهای UTM

پارامترهای UTM رشته‌هایی هستند که وقتی کاربران روی پیوند Assistant کلیک می‌کنند، Google Assistant به Action شما ارسال می‌کند. می توانید بعداً از اطلاعات موجود در این رشته ها برای تجزیه و تحلیل استفاده کنید.

پارامترهای UTM که Assistant به Action شما ارسال می کند شامل موارد زیر است:

utm_source
utm_medium
utm_campaign
utm_term
utm_content

مثال زیر نشان می‌دهد که چگونه می‌توانید یک URL پیوند دستیار که شامل پارامترهای UTM باشد را مشخص کنید:

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

برای مثال URL بالا، Assistant آرگومان های زیر را در پیام 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',
}

پیوندهای دستیار غنی

پیوندهای Rich Assistant راهی برای افزایش اکتشاف خود از طریق وب سایت خود با استفاده از help.js به شما می دهند. کاربران می توانند Action شما را امتحان کنند و همچنین حساب Google خود را با استفاده از پیوند حساب به سرویس شما پیوند دهند.

هنگامی که کاربر از وب سایت شما بازدید می کند، دکمه "با دستیار گوگل امتحان کنید" را می بیند که جریان پیوند دستیار غنی را فعال می کند.

فعال کردن پیوند حساب برای Action به کاربران امکان می‌دهد به Action شما در هر یک از دستگاه‌های دارای Assistant خود دسترسی داشته باشند. علاوه بر این، کاربران می‌توانند حساب کاربری خود را با سرویس شما به حساب Google خود پیوند دهند تا تجربه شخصی‌تری داشته باشند.

وقتی از پیوندهای «دستیار غنی» برای پیوند دادن حساب استفاده می‌شود، از URL مجوز شما استفاده می‌کند که در پروژه‌تان در کنسول Actions تنظیم شده است. برای اطلاعات بیشتر، به اسناد پیوند حساب مراجعه کنید.

پیش نیازها

برای استفاده از پیوندهای دستیار غنی، به موارد زیر نیاز دارید:

پروژه اقدامات .
پیوند دستیار برای Action شما فعال شد .
(اختیاری) پیوند حساب برای Action شما فعال شد .

توسعه محلی

برای قرار دادن پیوند دستیار غنی در وب سایت خود، مراحل زیر را انجام دهید:

کتابخانه جاوا اسکریپت زیر را در صفحه خود قرار دهید، و <PROJECT_ID> را با شناسه پروژه Actions خود جایگزین کنید:
```
<script async
src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
</script>
```
تگ HTML زیر را در جایی از صفحه خود اضافه کنید. این دکمه درون خطی «با دستیار Google امتحان کنید» را بارگیری می‌کند:
```
<google-assistant-link-group>
  
  <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> استفاده کنید. هنگامی که این برچسب را اعمال می کنید، پیوند بدون کاربران در اولین بازدید آنها فعال می شود، بدون اینکه آنها دکمه inline را انتخاب کنند.

یک 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-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>

استقرار

پیوندهای «دستیار غنی» فقط برای دامنه‌هایی که متعلق به شماست و با Google تأیید کرده‌اید کار می‌کنند. هنگام توسعه محلی، با دسترسی به پروژه Actions، وارد شدن به حساب Google خود و تنظیم پارامتر پرس و جو dev=true در تگ اسکریپت، این نیاز دور زده می شود.

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

برای استقرار Action خود با پیوندهای دستیار غنی:

دامنه عمومی خود را در کنسول Actions در زیر Deploy > Brand Verification > Connect Site ثبت کنید.

پارامتر dev=true query را از اسکریپت حذف کنید:

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

محدودیت ها و بهترین شیوه ها

محدودیت‌ها و بهترین شیوه‌های زیر اعمال می‌شوند تا URL پیوند دستیار شما خارج از فهرست راهنمای یا سایر سرویس‌های Google توزیع و ارجاع شود:

به پشتیبانی از همه پیوندهای دستیار خود ادامه دهید. اگر پیوند دستیار را توزیع کنید که بعداً خراب شود، ممکن است پروژه Actions شما به‌عنوان ناسالم علامت‌گذاری شود و حذف شود.
انتشار پیوند به این معنی است که از راه‌اندازی از منابع نامعتبر پشتیبانی می‌کنید. برای هر اقدام پیوندی، قبل از انجام هر اقدامی در دنیای واقعی باید صریحاً با کاربر تأیید کنید. به عنوان مثال، اقدامی که یک لوازم خانگی هوشمند را خاموش می کند، باید از کاربر بخواهد که بگوید: "آیا مطمئن هستید که می خواهید $applianceName خاموش کنید؟"
در این زمینه، عمل دنیای واقعی هر عملی است که بر خدمات، داده‌ها، دستگاه‌ها، شبکه‌ها، رایانه‌ها یا APIهای کاربر تأثیر می‌گذارد. به عنوان مثال، ارسال ایمیل، انجام تراکنش، تغییر وضعیت یک لوازم خانگی هوشمند، ایجاد اشتراک یا به‌روزرسانی یک محتوا.