پیام‌های iframe Looker تعبیه‌شده

۱. قبل از شروع

شما باید محتوای Looker را درون یک iframe با جاسازی خصوصی یا جاسازی SSO جاسازی کنید. در این آزمایشگاه کد، ما از طریق جاوا اسکریپت با iframe شما تعامل خواهیم کرد تا صفحه وب شما پویاتر شود. صفحه وب شما پیام‌هایی را به محتوای Looker جاسازی شده در iframe ارسال و از آن دریافت خواهد کرد.

پیش‌نیازها

آنچه یاد خواهید گرفت

  • چگونه iframe و نمونه Looker خود را برای تعامل با جاوا اسکریپت آماده کنیم؟
  • چگونه از iframe خود به رویدادها گوش دهیم
  • نحوه ارسال پیام‌های عملیاتی به iframe شما

آنچه نیاز دارید

  • دسترسی به HTML و جاوا اسکریپت کد frontend شما که iframe را مدیریت می‌کند
  • دسترسی به تنظیمات جاسازی ادمین در نمونه Looker شما

۲. آماده‌سازی‌ها

قبل از اینکه بتوانید با iframe تعامل داشته باشید، باید iframe و نمونه Looker خود را آماده کنید.

اضافه کردن یک ویژگی id به iframe

شما باید پیام‌های دریافتی از iframe را اعتبارسنجی کنید. برای انجام این کار، یک ویژگی id در iframe تعریف کنید:

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

دامنه‌ی جاسازی را به ویژگی src مربوط به iframe اضافه کنید.

دامنه صفحه وب میزبان iframe را تعیین کنید. فرض کنید آدرس اینترنتی صفحه وب https://mywebsite.com/with/embed باشد، آنگاه دامنه صفحه وب https://mywebsite.com خواهد بود.

اگر از جاسازی خصوصی (Private Embedding) استفاده می‌کنید، در src مربوط به iframe، دامنه را به عنوان پارامتر کوئری embed_domain اضافه کنید:

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

اگر از SSO Embedding استفاده می‌کنید، دامنه را به عنوان پارامتر کوئری embed_domain به آدرس اینترنتی embed اضافه کنید.

دامنه جاسازی را در نمونه Looker فهرست کنید.

در نهایت، برای اجازه ارسال پیام، باید دامنه جاسازی را در نمونه Looker خود به صورت allowlist تنظیم کنید.

به صفحه Embed در بخش مدیریت نمونه Looker خود بروید. https://your_instance.looker.com/admin/embed

در فیلد Embedded Domain Allowlis t، دامنه‌ی جاسازی‌شده را وارد کنید. پس از تایپ آن، کلید Tab را بزنید تا دامنه در یک کادر ظاهر شود. علامت اسلش / را در انتهای آن قرار ندهید.

دکمه به‌روزرسانی را انتخاب کنید.

۳. گوش دادن به پیام‌های رویداد از iframe

iframe شما با محتوای Looker جاسازی‌شده، پیام‌هایی را به صفحه وب میزبان خود ارسال می‌کند. این پیام‌های رویداد حاوی اطلاعات به‌موقع در مورد محتوای Looker جاسازی‌شده هستند، مانند اینکه آیا داشبورد جاسازی‌شده شروع به بارگیری کرده است یا کاربر گزینه دانلود را در محتوای جاسازی‌شده انتخاب کرده است. بیایید این رویدادها را دریافت و تجزیه کنیم.

درک طرحواره شیء رویداد

طرحواره شیء رویداد به صورت زیر است:

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

این رویداد همیشه یک ویژگی type خواهد داشت که به شما امکان می‌دهد نوع رویداد را تعیین کنید. سایر ویژگی‌های خاص رویداد در مرجع رویدادهای ما تعریف شده‌اند.

دریافت و تجزیه رویداد

این را به جایی که جاوا اسکریپت صفحه وب شما 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"); 
    }
  }
});

قطعه کد زیر کارهای زیر را انجام می‌دهد:

  1. به رویداد "message" از شیء window گوش می‌دهد.
  2. بررسی می‌کند که آیا ویژگی source پیام، iframe با محتوای Looker تعبیه‌شده است یا خیر.
  3. بررسی می‌کند که آیا ویژگی origin پیام، دامنه‌ی نمونه‌ی Looker شما است یا خیر.
  4. JSON ویژگی data پیام را تجزیه می‌کند تا به شیء رویداد دسترسی پیدا کرده و آن را تجزیه کند.
  5. ویژگی type شیء رویداد را فعال می‌کند تا مشخص کند چه رویدادی است و بر اساس آن عمل کند.

اکنون صفحه وب میزبان شما می‌تواند به صورت پویا به رویدادهایی که محتوای Looker جاسازی شده شما منتشر می‌کند، واکنش نشان دهد!

۴. ارسال پیام عملیاتی به iframe

صفحه وب میزبان شما همچنین می‌تواند پیام‌هایی را به محتوای Looker تعبیه‌شده در iframe شما ارسال کند. این پیام‌های عملیاتی می‌توانند وضعیت محتوای Looker تعبیه‌شده شما را تغییر دهند، مانند به‌روزرسانی فیلترها در داشبورد تعبیه‌شده شما. بیایید یک پیام عملیاتی ایجاد کنیم که به داشبورد تعبیه‌شده شما می‌گوید تا کوئری‌های خود را اجرا کرده و پیام را به iframe شما ارسال کند.

یک پیام عملیاتی ایجاد کنید

یک پیام عملیاتی درون جاوا اسکریپت صفحه وب خود ایجاد کنید:

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

شیء action از همان قالب شیء event قبلی پیروی می‌کند. همیشه یک ویژگی type و سپس ویژگی‌های خاص action خواهد داشت که در مرجع action ما تعریف شده‌اند. پیام action باید با فرمت JSON باشد.

پیام اقدام را ارسال کنید

درون جاوا اسکریپت صفحه وب خود، اکشن با فرمت JSON را به iframe خود ارسال کنید:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');
  1. iframe خود را که می‌خواهید عملیات خود را به آن ارسال کنید، تعیین کنید.
  2. برای ارسال پیام، متد postMessage() را در ویژگی contentWindow مربوط به iframe فراخوانی کنید.

اکنون صفحه وب میزبان شما می‌تواند به صورت پویا وضعیت محتوای Looker جاسازی شده شما را تغییر دهد!

۵. اطلاعات تکمیلی

تبریک! اکنون می‌توانید به رویدادها از محتوای Looker تعبیه‌شده در iframe خود گوش دهید و اقدامات را به آن ارسال کنید. برای اطلاعات بیشتر به این منابع مراجعه کنید: