הודעות iframe מוטמעות של Looker

1. לפני שמתחילים

צריך להטמיע תוכן של Looker בתוך iframe באמצעות הטמעה פרטית או הטמעה של כניסה יחידה (SSO). ב-codelab הזה, נשתמש ב-JavaScript כדי ליצור אינטראקציה עם ה-iframe שלכם, כדי להפוך את דף האינטרנט לדינמי יותר. דף האינטרנט ישלח הודעות לתוכן המוטמע של Looker ב-iframe ויקבל ממנו הודעות.

דרישות מוקדמות

יש לכם מופע פעיל של Looker
לוח בקרה של Looker שמוטמע באופן פרטי או מוטמע באמצעות כניסה יחידה (SSO) בתוך iframe
הסבר על השיטה window.postMessage()

מה תלמדו

איך מכינים את ה-iframe ואת מופע Looker לאינטראקציה עם JavaScript
איך מאזינים לאירועים מ-iframe
איך שולחים הודעות פעולה ל-iframe

מה תצטרכו

גישה לקוד ה-HTML ולקוד ה-JavaScript של ממשק הקצה שמנהל את ה-iframe
גישה להגדרות ההטמעה של האדמין במופע Looker

2. הכנות

כדי לנהל אינטראקציה עם ה-iframe, צריך להכין אותו ואת מופע Looker.

הוספת `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.

אם אתם משתמשים בהטמעה פרטית, מוסיפים את הדומיין כפרמטר שאילתה embed_domain ב-src של ה-iframe:

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

אם אתם משתמשים בהטמעה של כניסה יחידה, מוסיפים את הדומיין כפרמטר של שאילתת embed_domain לכתובת ה-URL להטמעה.

הוספת הדומיין של ההטמעה לרשימת ההיתרים במופע Looker

לבסוף, צריך להוסיף את הדומיין של ההטמעה לרשימת ההיתרים במופע Looker כדי לאפשר שליחת הודעות.

עוברים לדף Embed בקטע Admin במופע Looker. https://your_instance.looker.com/admin/embed

בשדה Embedded Domain Allowlist (רשימת ההיתרים של דומיינים להטמעה), מזינים את הדומיין של ההטמעה. אחרי שמקלידים את הדומיין, מקישים על המקש Tab כדי שהדומיין יופיע בתיבה. אין להוסיף קו נטוי בסוף /.

לוחצים על הלחצן עדכון.

3. האזנה להודעות אירועים מ-iframe

ה-iframe עם תוכן Looker המוטמע שולח הודעות לדף האינטרנט המארח שלו. הודעות האירוע האלה מכילות מידע עדכני על תוכן Looker המוטמע, למשל אם לוח הבקרה המוטמע התחיל להיטען או אם המשתמש בחר באפשרות ההורדה בתוך התוכן המוטמע. עכשיו נראה איך מקבלים ומנתחים את האירועים האלה.

הסבר על סכימת אובייקט האירוע

הסכימה של אובייקט האירוע היא:

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

לכל אירוע יש תמיד מאפיין type שמאפשר לכם לקבוע איזה אירוע זה. כל שאר המאפיינים הספציפיים לאירוע מוגדרים בהפניה לאירועים.

קבלת האירוע וניתוחו

מוסיפים את הקוד הבא למקום שבו קוד ה-JavaScript של דף האינטרנט מאתחל או מנהל את ה-iframe:

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"); 
    }
  }
});

קטע הקוד מבצע את הפעולות הבאות:

הקשבה לאירוע "message" מהאובייקט window.
בודק שהמאפיין source של ההודעה הוא ה-iframe עם תוכן Looker המוטמע.
בודק אם המאפיין origin של ההודעה הוא הדומיין של מופע Looker.
הפונקציה JSON מנתחת את המאפיין data של ההודעה כדי לגשת לאובייקט האירוע ולנתח אותו.
המתגים במאפיין 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');

קובעים את ה-iframe שאליו תשלחו את הפעולה.
מבצעים קריאה ל-postMessage() בנכס contentWindow של ה-iframe כדי לשלוח את ההודעה.

עכשיו דף האינטרנט המארח יכול לשנות באופן דינמי את המצב של תוכן Looker המוטמע!

5. מידע נוסף

מעולה! עכשיו אפשר להאזין לאירועים מתוכן Looker שמוטמע ב-iframe ולשלוח אליו פעולות. מידע נוסף זמין במקורות המידע הבאים:

הפניה לאירועים לכל האירועים הזמינים והמאפיינים שלהם
הפניה לפעולות לכל הפעולות הזמינות והמאפיינים שלהן
שיטות מומלצות לאבטחה בנוגע להטמעת תוכן Looker