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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بالنسبة إلى مثال عنوان URL أعلاه، يضيف "مساعد Google" في AppRequest عنصر JSON على النحو التالي:

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

معلّمات نظام مراقبة الزيارات من 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 " طريقة مساعِدة لزيادة إمكانية العثور على المهام من خلال موقعك الإلكتروني، وذلك باستخدام help.js. يمكن للمستخدمين تجربة "الإجراء"، بالإضافة إلى ربط حساب Google للخدمة، باستخدام عملية ربط الحسابات.

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

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

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

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

لاستخدام روابط "مساعد 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":

    <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؟".

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