الدمج مع موقع إلكتروني

لتوسيع نطاق وصول وكلاء ميزة "الرسائل التجارية"، يمكنك إضافة نقاط إدخال المحادثة على مواقعك الإلكترونية باستخدام أداة "الرسائل التجارية".

لا تعمل أداة "الرسائل التجارية" إلا على الأجهزة الجوّالة التي تعمل بالإصدار 5 من نظام التشغيل Android أو الإصدارات الأحدث. ولا تتوافق أنظمة تشغيل الجوّال وبيئات أجهزة سطح المكتب الأخرى مع تلك.

إضافة أداة "الرسائل التجارية" إلى موقع إلكتروني

لتفعيل المحادثات من موقع إلكتروني، عليك تحميل مكتبة JavaScript "للرسائل التجارية" وإعداد موضع الأداة على الصفحة وتحديد قيم السياق ضمن الأداة.

للحصول على قائمة بدوال مدى التوفّر والخصائص والأحداث، راجِع أداة "الرسائل التجارية" . اطّلِع على دليل نمط أداة "الرسائل التجارية" للحصول على اقتراحات بشأن التصميم والاستخدام.

إنشاء أداة

عدِّل القيم التالية لإنشاء أداة "الرسائل التجارية" لإدراجها في موقعك الإلكتروني.

القيمة الوصف
LAYOUT كيفية ظهور الزر في موقعك على الويب. يمكن أن تكون button أو floating أو inline أو advanced. لاستخدام أنماطك الخاصة، استخدم advanced، وانسخ ورقة الأنماط إلى صفحة الويب، وعدّلها حسب الحاجة.
AGENT_ID رقم تعريف الوكيل.
BUTTON_TEXT النص الذي تريد عرضه. 
    <script crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js"></script>
    <button data-bm-widget-layout="LAYOUT" data-bm-widget-agent-id="AGENT_ID">
      <span class="bm-widget-button-text">BUTTON_TEXT</span>
    </button>

نموذج أداة

يتم إنشاء هذه الأداة معاينة أداة الويب بواسطة الرمز التالي:

    <script crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js"></script>
    <button data-bm-widget-layout="button" data-bm-widget-agent-id="abcdefghijkl">
      <span class="bm-widget-button-text">Chat with us</span>
    </button>

تخصيص عملية دمج أداة "الرسائل التجارية"

تحميل مكتبة JavaScript

لتحميل مكتبة JavaScript لميزة "الرسائل التجارية"، انسخ الرمز التالي والصقه على الفور ضمن العلامة <head> في كل صفحة تريد عرض أداة "الرسائل التجارية" عليها. تحتاج فقط إلى تضمين مكتبة جافا سكريبت واحدة لكل صفحة.

<!-- Global Business Messages widget library reference - Business Messages -->
<script crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js?cb=callback">
</script>

يعمل المقتطف على تنزيل مكتبة JavaScript وتحميلها، ما يؤدي إلى إعداد عناصر الصفحة الحالية باستخدام السمة data-bm-widget-agent-id. تحوِّل مكتبة JavaScript عناصر الصفحة التي تم التعرّف عليها إلى عناصر قابلة للنقر عليها تعمل على تحميل لوحة محادثة "الرسائل التجارية" عند النقر عليها.

تتضمن المعلمة cb الاختيارية اسم دالة يتم استدعاؤها تلقائيًا عند تحميل مكتبة JavaScript.

تهيئة موضع الأداة

عندما يتم تحميل مكتبة JavaScript في "الرسائل التجارية"، فإنها تفحص الموقع الإلكتروني بحثًا عن عناصر تحتوي على السمة data-bm-widget-agent-id وتحول هذه العناصر إلى أدوات "الرسائل التجارية" قابلة للنقر عليها. يجب أن يشتمل كل عنصر تريد تحويله إلى أداة على سمة data-bm-widget-agent-id مع قيمة تتوافق مع معرّف الوكيل للوكيل الذي تم إطلاقه.

مثال: تعريفات الأدوات

<!-- Example div element that converts into a Business Messages widget -->
<div data-bm-widget-agent-id="myagentid">
  Click for Business Messages
</div>

<!-- Example button element that converts into a Business Messages widget -->
<button data-bm-widget-agent-id="myagentid">
  Click for Business Messages
</button>

تمرير قيم السياق

لضبط سياق الأداة وتمريره إلى الرد التلقائي على الويب، يُرجى تضمين السمة data-bm-widget-context الاختيارية في عنصر HTML الذي يحتوي على السمة data-bm-widget-agent-id. يُرجى تحديد قيمة لسلسلة data-bm-widget-context. تتضمن الرسائل المُرسَلة إلى الرد التلقائي على الويب قيمة السياق.

يمكن أن يكون لـ data-bm-widget-context أي قيمة، مثل قيمة ذات صلة بمكان عرض الأداة في وقت التشغيل على الصفحة. في الأمثلة التالية، قيمة السمة "eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==" هي سلسلة JSON بترميز base64 من {"product":"dryer","offer-code":"ASDADSA"}.

الحد الأقصى المسموح به في data-bm-widget-context هو 512 بايت.

مثال: تعريفات الأدوات مع السياق

<!-- Example div element that converts into a Business Messages widget -->
<div
  data-bm-widget-agent-id="myagentid"
  data-bm-widget-context="eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==">
  Click for Business Messages
</div>

<!-- Example button element that converts into a Business Messages widget -->
<button
  data-bm-widget-agent-id="myagentid"
  data-bm-widget-context="eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==">
  Click for Business Messages
</button>

نموذج لموقع إلكتروني

يُحمِّل النموذج التالي مكتبة JavaScript في "الرسائل التجارية" ضمن العلامة <head>، والتي تفحص بعد ذلك صفحة HTML تلقائيًا وتحوِّل "myagentid" إلى أدوات "الرسائل التجارية".

<html>
  <head>
    <script
      crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js">
    </script>
  </head>
  <body>
    This is a test widget:
    <div
      data-bm-widget-agent-id="myagentid"
      data-bm-widget-context="eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg==">
      Click for Business Messages
    </div>
    Click it.
    And this is a widget:
    <button
      data-bm-widget-agent-id="myagentid"
      data-bm-widget-context="VGhpcyBpcyBhIGJ1dHRvbiB0ZXN0Lgo=">
      Click for Business Messages
    </button>
  </body>
</html>

إعداد الأداة الآلية

للتحكم الدقيق في الإعداد، يمكنك اختيار تهيئة الأداة برمجيًا. لإعداد عنصر برمجيًا، يمكنك استدعاء bmwidget.init بعد تحميل مكتبة JavaScript في Business Messages. لا يتطلب هذا النوع من التهيئة وضع علامة على العناصر باستخدام السمة data-bm-widget-agent-id.

<head>
  <!-- Global Business Messages widget library reference - Business Messages -->
  <script
    crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js?cb=initWidget">
  </script>

  <script type="text/javascript">
    // Convert HTML element with ID = myCustomButton into a Business Messages widget
    function initWidget() {
      window.bmwidget.init(document.getElementById('myCustomButton'), {
        'agentId': 'myagentid',
        'context': 'eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg=='
      });
    };
  </script>
</head>

التحقق من دعم الجهاز

يمكنك استخدام window.bmwidget.supported للتحقُّق من دعم ميزة "الرسائل التجارية" لجهاز. يتحقّق النموذج التالي من دعم الأجهزة قبل تهيئة عنصر HTML برقم التعريف "myCustomButton" كأداة في ميزة "الرسائل التجارية".

<head>
  <!-- Global Business Messages widget library reference - Business Messages -->
  <script
    crossorigin="use-credentials" src="https://businessmessages.google.com/widget/v2/js?cb=initWidget">
  </script>

  <script type="text/javascript">
    // Convert HTML element with ID = myCustomButton into a Business Messages widget
    function initWidget() {
      // Check that the user has a supported device
      if (window.bmwidget.supported) {
        window.bmwidget.init(document.getElementById('myCustomButton'), {
          'agentId': 'myagentid',
          'context': 'eyJwcm9kdWN0IjoiZHJ5ZXIiLCJvZmZlci1jb2RlIjoiQVNEQURTQSJ9Cg=='
        });
      }
    };
  </script>
</head>

تهيئة الأداة لتطبيقات الصفحة الواحدة

بالنسبة إلى تطبيقات التطبيقات من صفحة واحدة، حيث يتم إنشاء السمة data-bm-widget-agent-id وقت التشغيل، تعرض مكتبة JavaScript في Business Messages كائنًا عموميًاwindow.bmwidget.

عندما تتم إضافة عنصر جديد إلى الصفحة، يمكنك استدعاء window.bmwidget.scan() لإعداد العنصر الجديد كأداة في "الرسائل التجارية".

window.bmwidget.scan();

يمكنك استدعاء window.bmwidget.scan() في استدعاء تحديث DOM للتأكد من إعادة تهيئة السمة data-bm-widget-agent-id عندما تغيّر الصفحة حالتها.

مثال زاوي

يعمل الرمز التالي على تهيئة window.bmwidget.scan() أثناء معاودة تحميل المكوّن في Angular.

import { Component, OnInit} from '@angular/core';

export class AppComponent implements onInit {
  ngOnInit() {
    // Initialize tag on re-render
    window.bmwidget.scan();
  }
}

مثال على رد فعل

يعمل الرمز التالي على تهيئة الدالة window.bmwidget.scan() أثناء عرض عنصر في React.

import React, { useState, useEffect } from 'react';

function WrapperComponent() {
  ...
  useEffect(() => {
    // Initialize on re-render
    window.bmwidget.scan();
  });

  return (<div><button data-bm-widget-agent-id="myagentid">Chat with us</button></div>);
}

الخطوات التالية

الآن بعد أن دمجت أداة "الرسائل التجارية" مع موقعك الإلكتروني، يمكنك بدء محادثات "الرسائل التجارية" من موقعك الإلكتروني وتلقّي قيم السياق الخاصة بالأدوات في رسائل المستخدمين.