1. قبل البدء
في هذا الدليل التعليمي حول الرموز البرمجية، سنستخدم حزمة تطوير البرامج (SDK) لميزة "تضمين Looker" لتضمين لوحة بيانات Looker في صفحة الويب. ستستدعي سلسلة من طرق حزمة تطوير البرامج (SDK) التي ستعمل تلقائيًا على إنشاء إطار iframe، وتضمين محتوى Looker فيه، وإعداد الاتصالات بين إطار iframe وصفحة الويب.
المتطلبات الأساسية
- توفُّر نسخة Looker قيد التشغيل
- توفُّر لوحة بيانات Looker تريد تضمينها في تطبيق الويب أو صفحة الويب
- الإلمام بخدمة JavaScript وJavaScript
المعلومات التي ستطّلع عليها
- كيفية التضمين بشكل خاص لمحتوى Looker باستخدام حزمة تطوير البرامج (SDK) لميزة "التضمين"
- كيفية إرسال الرسائل واستلامها (الإجراءات والأحداث) باستخدام محتوى Looker المضمّن مع حزمة تطوير البرامج (SDK) لميزة "دمج"
المتطلبات
- الوصول إلى HTML وJavaScript في رمز الواجهة الأمامية
- إذن الوصول إلى إعدادات تضمين المشرف في نسخة Looker
2. التحضيرات
عليك إعداد ملف HTML ومثيل Looker قبل أن تتمكّن من التضمين باستخدام حزمة تطوير البرامج (SDK) الخاصة بعملية التضمين.
إضافة عنصر حاوية إطار iframe المضمّن
في رمز HTML لصفحة الويب، أنشِئ عنصر div
وحدِّد فيه سمة id
.
<div id="looker-embed" />
إضافة نطاق التضمين إلى القائمة المسموح بها في مثيل Looker
يجب إضافة نطاق التضمين إلى القائمة المسموح بها في نسخة Looker.
حدِّد نطاق صفحة الويب التي تستضيف محتوى Looker المضمّن. لنفترض أنّ عنوان URL لصفحة الويب هو https://mywebsite.com/with/embed
، وبالتالي يكون نطاق صفحة الويب هو https://mywebsite.com
.
انتقِل إلى صفحة التضمين في قسم المشرف في مثيل Looker. https://your_instance.looker.com/admin/embed
في الحقل قائمة النطاقات المضمّنة المسموح بها، أدخِل نطاق التضمين. بعد كتابته، اضغط على مفتاح Tab لكي يظهر النطاق في مربّع. لا تضمِّن شَرطة مائلة لاحقة /
.
انقر على الزر تحديث.
3- إنشاء المحتوى المضمّن
لنبدأ الآن في إنشاء أداة إنشاء عمليات التضمين في حِزم تطوير البرامج (SDK) وضبطها من أجل "إنشاء" محتوى Looker المضمّن.
إعداد حزمة تطوير البرامج (SDK)
استورِد حزمة تطوير البرامج (SDK) أولاً ثم ابدأ إعدادها باستخدام نطاق مثيل Looker.
// Import the Embed SDK as LookerEmbedSDK
LookerEmbedSDK.init('instance_name.looker.com')
إنشاء أداة إنشاء التضمين
بعد ذلك، حدِّد رقم تعريف لوحة بيانات Looker التي تريد تضمينها. إذا كانت لوحة البيانات في instance_name.looker.com/dashboard/12345
، يكون رقم تعريفها هو 12345
.
لإنشاء أداة إنشاء تضمينات، عليك استدعاء طريقة createDashboardWithId()
في حزمة تطوير البرامج (SDK) باستخدام رقم تعريف لوحة البيانات. ستؤدي هذه الطريقة إلى عرض أداة إنشاء التضمين.
LookerEmbedSDK.createDashboardWithId(12345)
إعداد أداة إنشاء التضمينات وإنشاؤها
لنبدأ الآن في تكوين أداة إنشاء التضمينات قبل الطلب منها إنشاء إطار iframe المضمّن. أضِف نموذج التعليمات البرمجية التالي مباشرةً بعد استدعاء طريقة createDashboardWithId()
في نموذج التعليمات البرمجية السابق.
.appendTo(‘looker-embed')
.withFrameBorder(‘0')
.build()
تؤدي كل طريقة في أداة إنشاء التضمينات إلى عرض أداة إنشاء التضمين نفسها، وبالتالي نربط استدعاءات الطريقة معًا. لنستعرض كل طريقة:
- تحدِّد طريقة
appendTo()
العنصر الرئيسي لإطار iframe. نُدخل معرّف عنصر HTML الذي حدّدناه سابقًا في خطوة الإعداد. - تضبط الطريقة
withFrameBorder()
سمة frame-border في iframe. وهذه هي إحدى الطرق العديدة التي تحدّد سمات HTML في إطار iframe. - تنشئ الطريقة
build()
إطار iframe باستخدام سمات HTML التي تم ضبطها.
التحقّق النهائي
بعد تنفيذ الخطوات السابقة، من المفترض أن تظهر التعليمة البرمجية على النحو التالي:
// Import the Embed SDK as LookerEmbedSDK
LookerEmbedSDK.init('instance_name.looker.com')
LookerEmbedSDK.createDashboardWithId(12345)
.appendTo(‘looker-embed')
.withFrameBorder(‘0')
.build()
تم الآن تضمين لوحة بيانات Looker داخل صفحتك الإلكترونية باستخدام حزمة SDK المخصّصة للتضمين.
4. إرسال الرسائل المضمّنة وتلقّيها
لنلقِ الآن نظرة على كيفية إرسال الرسائل واستلامها باستخدام محتوى Looker المضمّن باستخدام حزمة تطوير البرامج (SDK) المضمَّنة. نُطلِق على الرسائل التي يرسلها تطبيقك إلى إطار iframe اسم الإجراءات، ونُطلِق على الرسائل التي يتلقّاها تطبيقك من إطار iframe اسم الأحداث.
تلقّي الأحداث
لنستخدم التعليمة البرمجية السابقة. وللاستماع إلى الأحداث، نستدعي طريقة on() الخاصة بأداة إنشاء التضمين قبل أن نستدعي الطريقة build()
.
...
.on('dashboard:run:complete',() => console.log(‘Embedded dashboard loaded!')
...
في ما يلي نُطلِق طريقة on()
لضبط أداة معالجة أحداث على حدث dashboard:run:complete
القادم من إطار iframe عند إنشاء إطار iframe. سيُعلمنا الحدث عند انتهاء تحميل لوحة البيانات. يمكنك الاطّلاع على مرجع الأحداث للاطّلاع على أحداث أخرى يمكنك الاستماع إليها.
إجراءات الإرسال
دعنا نستمر في التعليمات البرمجية السابقة. لإرسال الإجراءات إلى إطار iframe، نستدعي الطريقة connect()
في أداة إنشاء التضمينات بعد أن نستدعي طريقة build()
لإعداد إرسال الرسائل واستلامها باستخدام إطار iframe.
...
.connect()
.then((embed) => {
embed.send(‘dashboard:run');
})
.catch(console.error(‘Something errored!')
...
هيا نستعرض نموذج التعليمات البرمجية هذا:
- نستدعي الطريقة
connect()
التي تُرجع وعدًا. ويتحوّل الوعد إلى عنصر مضمّن يمثّل إطار iframe المضمّن بعد إعداد آلية إرسال الرسالة واستلامها. - ونستدعي الطريقة
send()
في كائن التضمين لإرسال إجراءdashboard:run
. يمكنك الاطّلاع على مرجع الإجراءات لمعرفة الإجراءات الأخرى التي يمكنك إرسالها. - نضيف طريقة
catch()
في حال حدوث أي أخطاء أثناء الإعداد.
المراجعة النهائية
بعد تنفيذ الخطوات السابقة، من المفترض أن تبدو التعليمة البرمجية الآن على النحو التالي:
// Import the Embed SDK as LookerEmbedSDK
LookerEmbedSDK.init('instance_name.looker.com')
LookerEmbedSDK.createDashboardWithId(12345)
.appendTo(‘looker-embed')
.withFrameBorder(‘0')
.on('dashboard:run:complete',() => console.log(‘Embedded dashboard loaded!')
.build()
.connect()
.then((embed) => {
embed.send(‘dashboard:run');
})
.catch(console.error(‘Something errored!')
يمكنك الآن التواصل مع لوحة بيانات Looker المضمّنة.
5- معلومات إضافية
تهانينا! يمكنك الآن استخدام حزمة تطوير البرامج (SDK) الخاصة بالإدراج لتضمين لوحة بيانات Looker بشكل خاص وإرسال الرسائل واستلامها من إطار iframe. اطّلِع على هذه المراجع للحصول على مزيد من المعلومات:
- مستودع حِزم تطوير البرامج (SDK) المضمّنة للحصول على مزيد من المعلومات حول كيفية تضمين Looker، خاصةً إذا كنت تريد تضمين Looker باستخدام الدخول المُوحَّد (SSO)
- مرجع الأحداث لجميع الأحداث المتاحة وخصائصها
- مرجع الإجراءات لكل الإجراءات المتاحة وخصائصها
- أفضل الممارسات المتعلقة بالأمان حول تضمين محتوى Looker