روابط "مساعد Google"

يمكنك إنشاء عنوان URL يؤدي مباشرة إلى هدف محدد من الإجراء. ويتم توجيه المستخدمين الذين ينقرون على رابط "مساعد Google" (المعروف سابقًا باسم روابط الإجراءات) في متصفّح الويب أو الأجهزة الجوّالة إلى "مساعد Google" على أجهزتهم، حيث يتفاعلون مباشرةً مع الإجراء.

تختلف روابط "مساعد Google" عن روابط دليل الويب، التي تنقل المستخدم إلى صفحة "الإجراء" في دليل "مساعد Google".

في ما يلي بعض الحالات التي يمكن أن تكون روابط "مساعد Google" فيها مفيدة:

• ربط المستخدمين بالتعليمات الإرشادية من موقع إلكتروني للإرشادات.
• ربط المستخدمين بتجربة دعم العملاء من صفحة المساعدة.
• ربط المستخدمين بقصد التحديث حتى يتمكنوا من تمكين تحديثاتك المستقبلية.

إنشاء رابط للمساعد

يمكنك إنشاء روابط "مساعد Google" من داخل مشروعك ضمن "وحدة تحكّم المهام". تتوفر روابط المساعد عبر جميع قنوات النشر (الإصدار الأولي والتجريبي والإنتاج). على سبيل المثال، إذا كان رابط "مساعد Google" مفعّلاً في الإصدار الأولي من المهمّة، سيكون الرابط متاحًا لمختبِري الإصدار الأولي.

لإنشاء عنوان URL لأحد الإجراءات، اتبع الخطوات التالية:

1. في وحدة تحكّم المهام، انتقِل إلى نشر > روابط "مساعد Google".
2. بالنسبة إلى النية بالشراء، اختَر الهدف الذي تريد إنشاء رابط له.
3. فعِّل الخيار هل تريد تفعيل الربط لـ intent_name؟.
4. (اختياري) في قسم معلّمات الحملات، أدخِل أي معلومات تريد الحصول عليها أيضًا في الرابط كمعلمات عناوين URL.
5. (اختياري) أدخِل عنوان الرابط. استخدِم هذا العنوان لوصف وظيفة الإجراء. على سبيل المثال، إذا كان الإجراء الذي تتخذه ينقل المستخدم إلى مسار المعاملة لشراء تذاكر لحضور حفل موسيقي، قد يكون عنوان الرابط هو "شراء تذاكر الحفلات الموسيقية".

بعد إدخال معلوماتك، يمكنك عرض ونسخ عنوان URL الذي تم إنشاؤه أو مقتطف الرمز الذي تم إنشاؤه لرابط "مساعد Google". يمكنك استخدام رابط "المساعد" في أي مكان لتوجيه المستخدمين إليه.

اختبار روابط "مساعد Google"

يمكنك اختبار روابط "مساعد Google" لأي غرض (أساسي أو مخصّص، باستخدام معلَمات أو بدونها) من خلال المحاكي أو على الجهاز.

لاختبار رابط "مساعد Google" على جهاز، اتّبِع الخطوات التالية:

1. أنشئ رابط "مساعد Google" في وحدة تحكّم "الإجراءات".
2. أرسِل رابط "مساعد Google" كعنوان URL لنفسك في رسالة إلكترونية أو رسالة محادثة أو أي تنسيق آخر.
3. على جهاز مزوّد بتطبيق "مساعد Google"، سجِّل الدخول إلى "مساعد Google" باستخدام الحساب نفسه الذي استخدمته لإنشاء مشروع "المهام".
4. على الجهاز نفسه، انقر على رابط "مساعد Google" الذي أرسلته إلى نفسك.

بعد التأكّد من عمل رابط "مساعد Google" على النحو المتوقّع، عليك إعادة نشر الإجراء ليصبح الرابط متاحًا للمستخدمين.

معلّمات روابط "مساعد Google"

يمكن أن تحتوي روابط "مساعد Google" بشكلٍ اختياري على intent ومعلمات في عنوان URL. استخدم قسم معلمات الحملة لإضافة معلمات الحملة.

عندما لا يحتوي رابط "مساعد Google" على معلّمات إضافية، يربط "مساعد Google" بهدف MAIN (actions.intent.MAIN) من الإجراء الخاص بك بالسلوك التالي:

• إذا لم يتم تفعيل intent في MAIN بشكل صريح في رابط "مساعد Google"، سيتطابق "مساعد Google" مع الغرض الرئيسي بدون أي معلَمات، على غرار سلوك "Talk to app_name".
• إذا فعّلت intent في MAIN صراحةً، يمرّر "مساعد Google" المعلَمات إلى الإجراءات.

في ما يلي مثال على عنوان URL لرابط "مساعد Google" باستخدام intent MAIN بدون معلَمات إضافية:

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

مواصفات عنوان URL لرابط "مساعد Google"

تكون البنية العامة لعنوان URL لرابط "مساعد Google" على النحو التالي:

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

يتم توضيح معلمات عناوين URL التي يمكنك تعيينها في الجدول التالي:

معلمة عنوان URL	الوصف
$action_id	المعرّف الرقمي للإجراء.
$intent	الاسم الكامل لقصد مستخدم أو هدف مدمج.
$param	الاسم الكامل لمعلمة intent المحددة في حزمة الإجراءات.
$value	قيمة عنوان URL المشفّرة من النوع المحدّد للخاصية $param في حزمة الإجراء.
$utm_param	قائمة بنوع معلمة واحد أو أكثر من نظام مراقبة الزيارات من Urchin وتشمل القيم الصالحة ما يلي: utm_source وutm_medium وutm_campaign وutm_term وutm_content.
$utm_value	قيمة السلسلة للمعلمة UTM.

عناوين URL لربط "مساعد Google" باستخدام عناصر intent المدمجة

إذا كان رابط "مساعد Google" يتضمّن هدفًا مدمجًا حسب النية بالشراء (يبدأ القصد من تشغيل actions.intent.)، سيحاول "مساعد Google" استخراج أي معلمات مضمّنة حسب النية بالشراء في عنوان URL وتمريرها إلى الإجراء. تتم إزالة أي معلّمات لا يفهمها "مساعد Google" على أنها معلّمات مضمّنة حسب النية بالشراء.

بالنسبة إلى "إجراءات المحادثة"، يرسل "مساعد Google" هذه المعلمات إلى توصيل الطلب كجزء من رسالة AppRequest.

يوضّح المثال التالي كيفية تحديد عنوان URL لرابط "مساعد Google" يتضمّن هدفًا مضمّنًا بمعلّمة intent فردية:

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

عناوين URL لربط "مساعد Google" بقصد المستخدمين

بالنسبة إلى نوايا المستخدم، لا يستخرج "مساعد Google" سوى تلك المعلّمات التي تم تحديدها من خلال الإجراء كجزء من intent ويتجاهل أي معلمات أخرى.

يوضّح المثال التالي كيفية تحديد عنوان URL لرابط "مساعد Google" يتضمّن نية المستخدم:

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" بمعلمات نظام مراقبة الزيارات من Urchin

معلَمات "نظام مراقبة الزيارات من Urchin" هي سلاسل يرسلها "مساعد Google" إلى الإجراء عند نقر المستخدمين على رابط "مساعد Google". يمكنك استخدام المعلومات الواردة في هذه السلاسل لاحقًا لإجراء التحليلات.

تتضمّن مَعلمات "نظام مراقبة الزيارات من Urchin" التي يرسلها "مساعد Google" إلى مهمتك ما يلي:

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content

يوضّح المثال التالي كيفية تحديد عنوان URL لرابط "مساعد Google" يتضمّن معلمات نظام مراقبة الزيارات من Urchin:

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

في مثال عنوان URL أعلاه، يضيف "مساعد 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" المنسّقة

تمنحك روابط "مساعد Google" الثرية طريقة لزيادة إمكانية اكتشاف "الإجراء" من خلال موقعك الإلكتروني، وذلك باستخدام help.js. يمكن للمستخدمين تجربة الإجراء، فضلاً عن ربط حساب Google بخدمتك، باستخدام ربط الحساب.

عندما يزور المستخدم موقعك الإلكتروني، سيظهر له الزر "تجربة باستخدام مساعد Google" الذي يؤدي إلى تشغيل تدفق رابط "مساعد Google".

يؤدي تفعيل ربط الحساب للإجراء إلى السماح للمستخدمين بالوصول إلى "الإجراء" الخاص بك على أي من أجهزتهم المزوّدة بخدمة "مساعد Google". بالإضافة إلى ذلك، يمكن للمستخدمين ربط حساباتهم في خدمتك بحساباتهم على Google، ما يتيح لهم الحصول على تجربة أكثر تخصيصًا.

عند استخدام روابط "مساعد Google" مع ربط الحساب، فإنها تستخدم عنوان URL للتفويض الذي تم ضبطه في مشروعك ضمن "وحدة تحكّم المهام". لمزيد من المعلومات، راجع مستندات ربط الحساب.

المتطلبات الأساسية

لاستخدام روابط "مساعد Google" المنسّقة، تحتاج إلى ما يلي:

• مشروع الإجراءات:
• تفعيل رابط "مساعد Google" لتنفيذ الإجراء
• (اختياري) تم تمكين ربط الحساب للإجراء.

التطوير المحلي

لتضمين رابط منسق من "مساعد Google" على موقعك الإلكتروني، يُرجى إكمال الخطوات التالية:

1. أدرِج مكتبة JavaScript التالية على صفحتك، مع استبدال <PROJECT_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" المنسّق تلقائيًا عند زيارة المستخدمين لصفحتك للمرة الأولى، استخدِم علامة <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>
   

التفعيل

لا تعمل روابط "مساعد Google" المنسّقة إلا مع النطاقات التي تملكها وتم إثبات ملكيتها من خلال Google. عند التطوير محليًا، يتم تجاوز هذا المطلب عن طريق الوصول إلى مشروع الإجراءات، وتسجيل الدخول إلى حسابك على Google، وضبط مَعلمة طلب البحث dev=true في علامة النص البرمجي.

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

لنشر المهمّة باستخدام روابط "مساعد Google" الغنية:

1. سجِّل نطاقك العام في وحدة تحكم الإجراءات ضمن نشر > إثبات ملكية العلامة التجارية > ربط موقع.

2. إزالة معلمة طلب البحث dev=true من النص البرمجي:

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

القيود وأفضل الممارسات

تنطبق القيود وأفضل الممارسات التالية بحيث يمكن توزيع عنوان URL لرابط "مساعد Google" والإشارة إليه خارج الدليل أو خدمات Google الأخرى:

• واصِل إتاحة استخدام جميع روابط "مساعد Google". إذا وزّعت رابط "مساعد Google" الذي يتعطل لاحقًا، قد يتم وضع علامة على مشروع الإجراءات الخاص بك على أنه غير صحي وتمت إزالته.

• ويعني نشر رابط أنك تسمح بتشغيل المحتوى من مصادر غير موثوق بها. وبالنسبة إلى أي إجراءات مرتبطة، يجب عليك التأكيد صراحةً مع المستخدم قبل اتخاذ أي إجراء فعلي. على سبيل المثال، يجب أن يطالب المستخدم الإجراء الذي يؤدي إلى إيقاف منزل مزوّد بأجهزة ذكية بالقول: "هل تريد بالتأكيد إيقاف $applianceName؟"

  وفي هذا السياق، فإن الإجراء الحقيقي هو أي إجراء يؤثر في خدمات المستخدم أو بياناته أو أجهزته أو شبكاته أو أجهزة كمبيوتره أو واجهات برمجة تطبيقاته. على سبيل المثال، إرسال رسالة إلكترونية أو إجراء معاملة أو تغيير حالة جهاز منزلي ذكي أو إنشاء اشتراك أو تحديث محتوى.