پیوند به اقدامات شما (Dialogflow)

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

چند نمونه از پیوندهای مفید دستیار عبارتند از:

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

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

برای ایجاد URL برای یک Action، موارد زیر را انجام دهید:

1. در «کنسول کنش‌ها» به Develop > Actions بروید.
2. روی اقدامی که می خواهید پیوندی برای آن ایجاد کنید کلیک کنید.
3. در بخش پیوندها ، Wid you like to enable a URL for this Action را فعال کنید.
4. عنوان پیوند را وارد کنید. این عنوان باید شامل یک فعل باشد که توصیف کننده کاری باشد که Action انجام خواهد داد. به عنوان مثال، اگر Action شما باعث کاهش جریان تراکنش برای خرید بلیط یک کنسرت شود، عنوان پیوند مفید «خرید بلیط کنسرت» خواهد بود.
5. روی ذخیره کلیک کنید.

می‌توانید URL ارائه‌شده را کپی کنید و به هر کجا که می‌خواهید کاربران را به این اکشن خاص هدایت کنید، ارجاع دهید.

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

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

پیوندهای دستیار می توانند به صورت اختیاری حاوی یک هدف و پارامترها در URL باشند. Google پارامترها را با توجه به نوع هدف مشخص شده در URL کنترل می کند.

مشخصات 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 سعی می‌کند هر پارامتر intent داخلی را در URL استخراج کرده و به Action شما ارسال کند. هر پارامتری که Google به‌عنوان پارامترهای هدف داخلی درک نمی‌کند، حذف می‌شوند.

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

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

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.GET_HOROSCOPE&param.astrologySign=%22cancer%22

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

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

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

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

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

argument {
  name: ‘topic’,
  raw_text: ‘sports’,
  text_value: ‘sports’,
}

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

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

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

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

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

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

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

پارامترهای UTM که Google به 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 بالا، گوگل آرگومان های زیر را در پیام 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’,
}

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

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

برای آزمایش پیوند دستیار:

1. پیوند Assistant را در کنسول فعال کنید.
2. با همان حسابی که برای ایجاد پروژه Actions on Google خود استفاده کردید، وارد Assistant شوید.
3. یک نسخه قابل کلیک از پیوند دستیار خود (در ایمیل، چت، سند و غیره) ایجاد کنید.
4. در دستگاهی که Assistant فعال است، روی پیوند ایجاد شده در مرحله قبل کلیک کنید.

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

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

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

از آنجایی که نشانی اینترنتی پیوند دستیار شما اکنون می‌تواند در خارج از فهرست راهنمای یا سایر خدمات Google توزیع و ارجاع داده شود، لطفاً توجه داشته باشید که محدودیت‌ها و بهترین شیوه‌های زیر اعمال می‌شود:

• مطمئن شوید که به پشتیبانی از همه پیوندهای دستیار خود ادامه می دهید. اگر پیوند دستیار را توزیع کنید که بعداً خراب شود، ممکن است پروژه Actions شما به‌عنوان ناسالم علامت‌گذاری شود و حذف شود.

• انتشار پیوند به این معنی است که از راه‌اندازی از منابع نامعتبر پشتیبانی می‌کنید. برای هر اقدام پیوندی، باید قبل از انجام هر «اقدامی در دنیای واقعی» صریحاً با کاربر تأیید کنید. برای مثال، اقدامی که یک دستگاه هوشمند خانگی را خاموش می‌کند، باید از کاربر بخواهد که بگوید "آیا مطمئن هستید که می‌خواهید $applianceName را خاموش کنید؟"

  در این زمینه، "عمل دنیای واقعی" هر عملی است که بر خدمات، داده ها، دستگاه ها، شبکه ها، رایانه ها یا APIهای کاربر تأثیر می گذارد. به عنوان مثال، ارسال ایمیل، انجام تراکنش، تغییر وضعیت یک دستگاه خانه هوشمند، ایجاد اشتراک، یا به‌روزرسانی یک محتوا.