مراسلة إطار iframe في Looker المُضمَّنة

1. قبل البدء

يجب أن يكون محتوى Looker مضمّنًا داخل إطار iframe مع تضمين خاص أو تضمين الدخول المُوحَّد (SSO). في هذا الدليل التعليمي حول الرموز البرمجية، سنتفاعل مع إطار iframe من خلال JavaScript لجعل صفحتك على الويب أكثر ديناميكية. سترسل صفحتك على الويب رسائل إلى محتوى Looker المضمَّن في إطار iframe، كما ستستلمها.

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

المعلومات التي ستطّلع عليها

  • كيفية إعداد إطار iframe ومثيل Looker للتفاعل مع JavaScript
  • كيفية الاستماع إلى الأحداث من إطار iframe
  • كيفية إرسال رسائل الإجراءات إلى إطار iframe

المتطلبات

  • الوصول إلى رمز HTML وJavaScript في رمز الواجهة الأمامية الذي يدير إطار iframe
  • الوصول إلى إعدادات تضمين المشرف في نسخة Looker

2. التحضيرات

تحتاج إلى إعداد iframe ونسخة Looker قبل أن تتمكّن من التفاعل مع iframe.

إضافة سمة id إلى إطار iframe

عليك التحقّق من صحة الرسائل الواردة من إطار iframe. لإجراء ذلك، حدِّد السمة id على إطار iframe:

<iframe 
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1"
>
</iframe>

أضِف نطاق التضمين إلى سمة src لإطار iframe.

حدِّد نطاق صفحة الويب التي تستضيف إطار iframe. لنفترض أن عنوان URL لصفحة الويب هو https://mywebsite.com/with/embed، ثم نطاق صفحة الويب هو https://mywebsite.com.

إذا كنت تستخدم التضمين الخاص، في src لإطار iframe، أضِف النطاق كمَعلمة طلب بحث embed_domain:

<iframe
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"
>
</iframe>

إذا كنت تستخدم ميزة التضمين باستخدام الدخول المُوحَّد (SSO)، أضِف النطاق كمَعلمة طلب بحث embed_domain إلى عنوان URL التضمين.

إضافة نطاق التضمين إلى القائمة المسموح بها في نسخة Looker

أخيرًا، يجب إضافة نطاق التضمين إلى القائمة المسموح بها في نسخة Looker للسماح بإرسال الرسائل.

انتقِل إلى صفحة التضمين في قسم المشرف في مثيل Looker. https://your_instance.looker.com/admin/embed

في الحقل السماح للنطاق المضمّن، أدخِل نطاق التضمين. بعد كتابته، اضغط على مفتاح Tab لكي يظهر النطاق في مربّع. لا تُدرِج شرطة سفلية /.

انقر على الزر تعديل.

3- الاستماع إلى رسائل الأحداث من إطار iframe

يُرسِل إطار iframe الذي يتضمّن محتوى Looker مضمّنًا رسائل إلى صفحة الويب المضيفة. تحتوي رسائل الفعاليات هذه على معلومات في الوقت المناسب حول محتوى منصة العرض المضمّن، مثلاً ما إذا كان قد بدأ تحميل لوحة البيانات المضمّنة أو إذا حدّد المستخدم خيار التنزيل ضمن المحتوى المضمَّن. لنتلقّى هذه الأحداث ونحلّلها.

فهم مخطط عنصر الحدث

مخطّط عنصر الحدث هو:

{
  type: "...",
  eventSpecificProperty1: ...,
  eventSpecificProperty2: ...,
  ...
}

سيحتوي الحدث دائمًا على السمة type التي تتيح لك تحديد الحدث. ويتم تحديد جميع السمات الأخرى الخاصة بالحدث في مرجع الأحداث لدينا.

استلام الحدث وتحليله

أضِف هذا الحقل إلى المكان الذي يتم فيه إعداد أو إدارة إطار iframe في صفحة الويب باستخدام JavaScript:

window.addEventListener("message", function(message) {
  const iframeElement = document.getElementById("looker");
  if (message.source === iframeElement.contentWindow) {
    if (message.origin === "https://instance_name.looker.com") {
      const event = JSON.parse(message.data);
      switch (event.type):
        case "dashboard:run:start":
          console.log("The embedded dashboard has started loading"); 
    }
  }
});

ينفِّذ مقتطف الرمز البرمجي ما يلي:

  1. يرصد الحدث "message" من الكائن window.
  2. التحقّق من أنّ سمة source للرسالة هي إطار iframe الذي يتضمّن محتوى Looker المضمّن
  3. للتحقّق من أنّ السمة origin للرسالة هي نطاق مثيل Looker.
  4. يُحلِّل تنسيق JSON سمة data للرسالة للوصول إلى كائن الحدث وتحليله.
  5. تشغّل هذه السمة العنصر type في كائن الحدث لتحديد نوع الحدث واتّخاذ إجراء بشأنه.

يمكن الآن لصفحة الويب المضيف التفاعل ديناميكيًا مع الأحداث التي يُرسِلها محتوى Looker المضمّن.

4. إرسال رسالة الإجراء إلى إطار iframe

يمكن لصفحة الويب المضيفة أيضًا إرسال رسائل إلى محتوى Looker المضمّن في إطار iframe. يمكن أن تؤدي رسائل الإجراءات هذه إلى تغيير حالة محتوى Looker المضمّن، مثل تعديل الفلاتر في لوحة البيانات المضمّنة. لننشئ رسالة إجراء تطلب من لوحة البيانات المضمّنة تنفيذ طلبات البحث وإرسال الرسالة إلى إطار iframe.

إنشاء رسالة إجراء

إنشاء رسالة إجراء داخل JavaScript على صفحة الويب:

const action = { type: "dashboard:run" };
const actionJSONFormatted = JSON.stringify(action);

يتّبع عنصر action التنسيق نفسه المستخدَم في عنصر event السابق. ستحتوي دائمًا على السمة type ثم سمات خاصة بإجراءات محدّدة في مرجع الإجراء. يجب أن تكون رسالة الإجراء بتنسيق JSON.

إرسال رسالة الإجراء

داخل JavaScript في صفحة الويب، أرسِل الإجراء بتنسيق JSON إلى إطار iframe:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');
  1. حدِّد إطار iframe الذي سترسل إليه الإجراء.
  2. يمكنك استدعاء طريقة postMessage() في السمة contentWindow الخاصة بإطار iframe لإرسال الرسالة.

يمكن الآن لصفحة الويب المضيف تغيير حالة محتوى Looker المضمّن ديناميكيًا.

5- معلومات إضافية

تهانينا! يمكنك الآن الاستماع إلى الأحداث من محتوى Looker المضمّن في إطار iframe وإرسال الإجراءات إليه. اطلع على هذه الموارد لمزيد من المعلومات: