روابط "مساعد 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" معلَمات إضافية، يرتبط "مساعد Google" بهدف MAIN (actions.intent.MAIN) من الإجراء الخاص بك باتّباع السلوك التالي:

  • إذا لم تفعّل ميزة الغرض MAIN بشكل صريح في رابط "مساعد Google"، سيطابق "مساعد Google" الغرض الرئيسي بدون أي معلَمات، تمامًا مثل سلوك "التحدّث إلى app_name".
  • إذا فعّلت الغرض من 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 الاسم الكامل لمعلَمة الغرض المحدّدة في حزمة الإجراءات.
$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 المثالي أعلاه، في AppRequest، يضيف "مساعد Google" عنصر 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',
}

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

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

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

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

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

لاستخدام روابط "المساعد المنسّق"، يجب أن يتوفّر لديك ما يلي:

التنمية المحلية

لتضمين رابط يؤدّي إلى "مساعد 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؟"

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