Pengantar Embed SDK

Catatan: Halaman ini adalah referensi untuk Embed SDK 2.0.0. Meskipun API 2.0.0 kompatibel dengan Embed SDK 1.8.x, penerapan yang mendasarinya telah berubah untuk beberapa fungsi. SDK 1.8.x mengekspor sejumlah class. SDK 2.0.0 menggantikan class ini dengan antarmuka yang ditandai sebagai tidak digunakan lagi (antarmuka alternatif diidentifikasi). Sebaiknya aplikasi menggunakan antarmuka yang memiliki awalan 'I' (antarmuka yang memiliki awalan identik dengan antarmuka yang tidak memilikinya). Aplikasi yang diupgrade ke SDK 2.0.0 akan terus berfungsi dan berperilaku seperti sebelumnya. Untuk memanfaatkan peningkatan API, beberapa refaktorisasi akan diperlukan. Perubahan besar berikut disertakan dalam Embed SDK 2.0.0:

• Beralih antar-dasbor, Eksplorasi, dan Look tidak lagi memerlukan pembuatan ulang iframe. Sebagai gantinya, metode loadDashboard, loadLook, loadExplore, dan loadUrl dapat digunakan untuk membuka halaman dalam iframe Looker.
• connect kini menampilkan koneksi terpadu, bukan koneksi yang hanya terkait dengan dasbor, Look, atau Eksplorasi. Koneksi terpadu memungkinkan aplikasi penyematan mendeteksi pengguna yang menjelajahi iframe.
• Dukungan untuk konten tersemat Looker tambahan telah ditambahkan untuk laporan Looker dan visualisasi kueri.

Looker Embed SDK adalah library fungsi yang dapat Anda tambahkan ke kode aplikasi web berbasis browser untuk mengelola dasbor, Look, laporan, dan Eksplorasi yang disematkan di aplikasi web Anda.

Catatan: Laporan Looker tersedia jika fitur laporan Looker diaktifkan. Laporan dapat disematkan dengan metode sematan bertanda tangan, metode sematan tanpa cookie, atau metode sematan pribadi. Untuk mengetahui detail selengkapnya, lihat Menyematkan laporan Looker.

Embed SDK memfasilitasi penyematan dengan cara berikut:

• Menyediakan enkapsulasi konten yang disematkan tanpa perlu membuat elemen HTML secara manual.
• Menyediakan komunikasi point-to-point sehingga tidak ada komunikasi lintas frame. Embed SDK menangani penerusan pesan lintas domain antara halaman web host dan konten Looker yang disematkan, dengan memanfaatkan saluran pesan khusus.

Tanpa Embed SDK, Anda dapat memanggil atau merespons peristiwa dalam konten Looker yang disematkan menggunakan peristiwa JavaScript seperti dashboard:run:start atau page:changed, yang dijelaskan di halaman dokumentasi Peristiwa JavaScript yang disematkan. Developer yang menyematkan konten Looker dengan peristiwa JavaScript harus membuat elemen HTML untuk menampung konten yang disematkan dan mengandalkan peristiwa siaran jendela untuk komunikasi antara aplikasi web dan konten yang disematkan.

Perhatikan bahwa Looker Embed SDK berbeda dengan Looker API dan Looker API SDK:

• Looker Embed SDK berada di kode sisi klien aplikasi web Anda dan mengelola konteks serta konten sematan Looker. (Embed SDK tidak memberikan akses ke Looker API.)
• Looker API berada di server dengan instance Looker Anda dan menjalankan perintah di server Looker.
• SDK klien Looker API berada di kode aplikasi non-browser untuk memberikan akses ke fungsi Looker API.

Perlu diketahui bahwa Looker tidak mengontrol urutan pengiriman peristiwa browser ke aplikasi web. Artinya, urutan peristiwa tidak dijamin di seluruh browser atau platform. Pastikan Anda menulis JavaScript dengan tepat untuk memperhitungkan penanganan peristiwa di berbagai browser.

Contoh cepat

Dalam contoh ini, dasbor dengan ID 11 dibuat di dalam elemen DOM dengan ID embed_container. Peristiwa dashboard:run:start dan dashboard:run:complete digunakan untuk memperbarui status UI jendela penyematan, dan tombol dengan ID run diberi skrip untuk mengirim pesan dashboard:run ke dasbor.

getEmbedSDK().init('looker.example.com', '/auth')

const setupConnection = (connection) => {
  document.querySelector('#run').addEventListener('click', () => {
    connection.asDashboardConnection().run()
  })
}

try {
  connection = await getEmbedSDK()
    .createDashboardWithId('11')
    .appendTo('#embed_container')
    .on('dashboard:run:start', () => updateStatus('Running'))
    .on('dashboard:run:complete', () => updateStatus('Done'))
    .build()
    .connect()
  setupConnection(connection)
} catch (error) {
  console.error('An unexpected error occurred', error)
}

Contoh yang lebih lengkap dijelaskan di halaman dokumentasi Demo Embed SDK.

Menyiapkan Looker Embed SDK

Looker Embed SDK menggunakan pola antarmuka yang lancar. Setelah menginstal Embed SDK, Anda kemudian membuat konten sematan dan menghubungkan ke konten sematan. Aplikasi hosting dapat berinteraksi dengan konten yang disematkan setelah koneksi dibuat.

Menginstal Embed SDK

Anda bisa mendapatkan library Looker Embed SDK melalui pengelola paket node (NPM) di https://www.npmjs.com/package/@looker/embed-sdk. Namun, jika ingin melihat kode contoh atau demo, Anda harus menggunakan repositori Looker Embed SDK.

Untuk menginstal Looker Embed SDK menggunakan repositori Looker Embed SDK, ikuti langkah-langkah berikut:

1. Instal Node.js, jika Anda belum memilikinya.
2. Download atau clone repositori /looker-open-source/embed-sdk.
3. Di jendela terminal, buka direktori /embed-sdk dan jalankan perintah berikut:

npm install
npm start

Membuat konten yang disematkan

Pertama, lakukan inisialisasi SDK dengan alamat server Looker dan endpoint server aplikasi penyematan yang akan membuat URL login sematan Looker bertanda tangan. Server ini digunakan oleh semua konten sematan. Untuk penyematan pribadi, hapus endpoint penandatanganan.

Catatan: Sertakan nomor port jika diperlukan untuk menjangkau server Looker dari klien browser. Contoh: looker.example.com:443

getEmbedSDK().init('looker.example.com', '/auth')

Kemudian, konten sematan dibuat menggunakan serangkaian langkah untuk menentukan parameternya. Beberapa parameter ini bersifat opsional, dan beberapa bersifat wajib.

Proses ini dimulai dengan membuat builder menggunakan dasbor id atau url yang merujuk ke dasbor (dibuat oleh proses yang dijelaskan di halaman dokumentasi Penyematan bertanda tangan).

getEmbedSDK().createDashboardWithId('id')

atau

getEmbedSDK().createDashboardWithUrl('url')

Kemudian, Anda dapat menambahkan atribut tambahan ke builder untuk menyelesaikan penyiapan.

Catatan: Fungsi create[ContentType]WithUrl dapat digunakan dengan sematan bertanda tangan dan tanpa cookie mulai dari Embed SDK 2.0.0. Sebelum Embed SDK 2.0.0, sematan tanpa cookie hanya mendukung create[ContentType]WithId.

Misalnya, Anda dapat menentukan tempat di halaman web untuk menyisipkan UI sematan Looker. Panggilan berikut menempatkan UI sematan Looker di dalam elemen HTML dengan nilai ID dashboard:

.appendTo('#dashboard')

Menambahkan pengendali peristiwa:

.on('dashboard:run:start',
  () => updateStatus('Running')
)
.on('dashboard:run:complete',
  () => updateStatus('Done')
)

Buat klien sematan dengan memanggil metode build:

.build()

Menghubungkan ke konten yang disematkan

Setelah klien dibuat, panggil connect untuk membuat iframe. Proses koneksi membuat atribut src yang digunakan untuk iframe sebenarnya. Cara nilai src dibuat didasarkan pada cara Embed SDK diinisialisasi:

1. Bertanda tangan: Endpoint yang ditentukan oleh argumen kedua panggilan init dipanggil. Endpoint diharapkan menampilkan URL login penyematan yang ditandatangani.
2. Tanpa cookie: Endpoint atau fungsi yang ditentukan oleh argumen kedua panggilan initCookieless dipanggil. Endpoint atau fungsi diharapkan menampilkan token tanpa cookie, khususnya token autentikasi dan navigasi. Token ditambahkan ke URL login sematan.
3. Pribadi: Koneksi sematan bersifat pribadi jika argumen kedua dari panggilan init tidak diberikan. Dalam hal ini, URL berasal dari builder dan dihiasi dengan parameter yang diperlukan untuk sematan Looker. Untuk sematan pribadi, pengguna diharapkan sudah login ke Looker atau URL sematan menyertakan parameter allow_login_screen=true.

connect menampilkan Promise yang di-resolve ke antarmuka koneksi untuk iframe sematan.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

Berinteraksi

Embed SDK 2.0.0 menampilkan koneksi terpadu yang mendukung interaksi dengan semua jenis konten Looker. Aplikasi penyematan dapat menentukan jenis konten yang ditampilkan dan berinteraksi dengan tepat.

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

Iframe tidak perlu dibuat ulang saat konten yang berbeda perlu dimuat. Sebagai gantinya, metode koneksi loadDashboard, loadLook, loadExplore, atau loadUrl dapat digunakan. Metode loadDashboard, loadLook, dan loadExplore menerima id. Metode loadUrl menerima sematan URL, dan metode ini dapat digunakan untuk menentukan parameter tambahan (seperti filter).

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

Jika perlu membuat iframe baru, Embed SDK tidak akan memanggil endpoint penandatanganan atau perolehan sesi lagi. Sebagai gantinya, iframe src akan dibuat langsung dari builder. Jika sesi sematan baru perlu dibuat, Embed SDK harus diinisialisasi ulang dengan cara berikut:

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

Endpoint autentikasi URL yang ditandatangani

Bagian ini tidak berlaku untuk sematan tanpa cookie. Lihat Penyematan tanpa cookie untuk mengetahui detailnya.

Untuk menggunakan Embed SDK, Anda harus menyediakan layanan backend yang menangani penandatanganan URL sematan. Layanan ini dipanggil oleh Embed SDK untuk membuat URL bertanda tangan yang unik bagi pengguna yang membuat permintaan. Proses backend dapat membuat URL sematan bertanda tangan itu sendiri dengan menggunakan rahasia sematan, atau proses backend dapat membuat URL dengan memanggil Looker Create Signed Embed URL API. Penandatanganan dan pembuatan URL manual menghindari panggilan Looker API, yang mengurangi latensi. Memanggil Looker API memerlukan lebih sedikit kode dan lebih mudah dikelola.

Contoh JavaScript dari metode helper yang menghasilkan URL yang ditandatangani, createSignedUrl(), dapat ditemukan di server/utils/auth_utils.ts. Cara penggunaannya adalah sebagai berikut:

import { createSignedUrl } from './utils/auth_utils'

app.get('/looker_auth', function (req, res) {
  // It is assumed that the request is authorized
  const src = req.query.src
  const host = 'looker.example.com'
  const secret = ... // Embed secret from Looker Server Embed Admin page
  const user = ... // Embedded user definition
  const url = createSignedUrl(src, user, host, secret)
  res.json({ url })
})

Lihat contoh python di repositori.

Konfigurasi autentikasi lanjutan URL yang ditandatangani

Bagian ini tidak berlaku untuk sematan tanpa cookie. Lihat Penyematan tanpa cookie untuk mengetahui detailnya.

Anda dapat mengonfigurasi endpoint autentikasi untuk mengizinkan header permintaan kustom dan dukungan CORS dengan meneruskan objek opsi ke metode init.

getEmbedSDK().init('looker.example.com', {
  url: 'https://api.acme.com/looker/auth',
  headers: [{ name: 'Foo Header', value: 'Foo' }],
  params: [{ name: 'foo', value: 'bar' }],
  withCredentials: true, // Needed for CORS requests to Auth endpoint include Http Only cookie headers
})

Pemecahan masalah

Embed SDK dibangun di atas chatty. Chatty menggunakan debug untuk mencatat log. Anda dapat mengaktifkan logging di konsol browser dengan perintah ini:

localStorage.debug = 'looker:chatty:*'
```none

Note that both the parent window and the embedded content have separate local storage, so you can enable logging on one, the other, or both. You can disable logging with this command:

```javascript
localStorage.debug = ''