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, implementasi yang mendasarinya telah berubah untuk beberapa fungsi. SDK 1.8.x mengekspor sejumlah class. SDK 2.0.0 mengganti 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 refactoring akan diperlukan. Perubahan besar berikut disertakan dalam Embed SDK 2.0.0:

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

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

Catatan: Laporan Looker tersedia saat fitur laporan Looker diaktifkan. Laporan dapat disematkan dengan metode sematan yang ditandatangani, 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 tersemat 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 tersemat, dengan menggunakan saluran pesan khusus.

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

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

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

Perhatikan bahwa Looker tidak mengontrol urutan browser mengirimkan peristiwa ke aplikasi web. Artinya, urutan peristiwa tidak dijamin di seluruh browser atau platform. Pastikan untuk menulis JavaScript dengan tepat untuk memperhitungkan penanganan peristiwa browser yang berbeda.

Contoh singkat

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 dibuat skripnya 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 akan membuat konten tersemat dan terhubung ke konten tersemat. Aplikasi hosting dapat berinteraksi dengan konten tersemat setelah koneksi dibuat.

Menginstal Embed SDK

Anda bisa mendapatkan library Embed SDK Looker 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 tersemat

Pertama, inisialisasi SDK dengan alamat server Looker dan endpoint server aplikasi penyematan yang akan membuat URL login tersemat Looker yang ditandatangani. Server ini digunakan oleh semua konten tersemat. 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 tersemat dibuat menggunakan serangkaian langkah untuk menentukan parameternya. Beberapa parameter ini bersifat opsional, dan beberapa lainnya wajib.

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

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 yang ditandatangani 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')

Tambahkan pengendali peristiwa:

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

Buat klien tersemat dengan memanggil metode build:

.build()

Menghubungkan ke konten tersemat

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 SDK sematan diinisialisasi:

1. Ditandatangani: Endpoint yang ditentukan oleh argumen kedua dari panggilan init dipanggil. Endpoint diharapkan menampilkan URL login sematan yang ditandatangani.
2. Tanpa cookie: Endpoint atau fungsi yang ditentukan oleh argumen kedua dari 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 penyematan menyertakan parameter allow_login_screen=true.

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

  .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 URL sematan, 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 sesi perolehan lagi. Sebagai gantinya, iframe akan membuat src langsung dari builder. Jika perlu membuat sesi sematan baru, 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 yang ditandatangani yang unik untuk pengguna yang meminta. Proses backend dapat membuat URL sematan yang ditandatangani sendiri menggunakan rahasia sematan, atau proses backend dapat membuat URL dengan memanggil Looker Create Signed Embed URL API. Pembuatan dan penandatanganan 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 membuat URL yang ditandatangani, createSignedUrl(), dapat ditemukan di server/utils/auth_utils.ts. Metode ini digunakan dengan cara 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 dibuat berdasarkan chatty. Chatty menggunakan debug untuk logging. 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 = ''