Perlu diperhatikan bahwa Anda sedang melihat dokumentasi Looker. Untuk melihat dokumentasi Looker Studio, buka https://support.google.com/looker-studio.

Pengantar Embed SDK

Embed SDK Looker adalah library fungsi yang dapat Anda tambahkan ke kode aplikasi web berbasis browser untuk mengelola dasbor, Tampilan, dan Jelajah tersemat di aplikasi web Anda. Embed SDK memfasilitasi penyematan dengan cara berikut:

Menyediakan enkapsulasi konten tersemat tanpa perlu membuat elemen HTML secara manual.
Menyediakan komunikasi titik ke titik sehingga tidak ada komunikasi lintas bingkai. Embed SDK menangani pesan lintas-domain yang diteruskan antara halaman web host dan konten Looker sematan Anda, menggunakan saluran pesan khusus.

Tanpa Embed SDK, Anda dapat memanggil atau merespons peristiwa di 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 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 dalam kode sisi klien dari aplikasi web Anda serta mengelola konteks dan konten sematan Looker. (Embed SDK tidak menyediakan akses ke Looker API).
Looker API berada di server dengan instance Looker Anda dan menjalankan perintah di server Looker.
SDK klien Looker API berada dalam kode aplikasi non-browser untuk memberikan akses mudah ke fungsi Looker API.

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

Contoh cepat

Contoh ini membuat konteks penyematan Looker, memasukkannya ke elemen DOM dengan ID dashboard, lalu menampilkan dasbor dengan ID 11 dalam konteks sematan Looker. Peristiwa dashboard:run:start dan dashboard:run:complete digunakan untuk memperbarui status UI jendela penyematan, dan tombol dengan ID run ditulis dengan skrip untuk mengirim pesan dashboard:run ke dasbor.

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

const setupDashboard = (dashboard) => {
  document.querySelector('#run').addEventListener('click', () => {
    dashboard.send('dashboard:run')
  })
}

LookerEmbedSDK.createDashboardWithId(11)
  .appendTo('#dashboard')
  .on('dashboard:run:start',
      () => updateState('#dashboard-state', 'Running')
  )
  .on('dashboard:run:complete',
      () => updateState('#dashboard-state', 'Done')
  )
  .build()
  .connect()
  .then(setupDashboard)
  .catch((error: 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 menghubungkan ke konten tersemat.

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 Anda ingin melihat kode contoh atau demo, sebaiknya gunakan repositori Looker Embed SDK.

Untuk menginstal Looker Embed SDK menggunakan repo Looker Embed SDK:

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

npm install
npm start

Membuat konten sematan

Pertama, inisialisasi SDK dengan alamat server web Anda dan, secara opsional, endpoint di server Anda yang akan melakukan autentikasi. Atribut ini digunakan oleh semua konten yang disematkan.

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

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

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

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

LookerEmbedSDK.createDashboardWithId(id)

atau

LookerEmbedSDK.createDashboardWithUrl(url)

Anda kemudian dapat menambahkan atribut tambahan pada builder untuk menyelesaikan pengaturan. Misalnya, Anda dapat menentukan tempat menyisipkan UI sematan Looker di halaman web. Panggilan berikut menempatkan UI sematan Looker di dalam elemen HTML dengan nilai ID dashboard:

.appendTo('#dashboard')

Anda dapat menambahkan pengendali peristiwa:

.on('dashboard:run:start',
  () => updateState('#dashboard-state', 'Running')
)
.on('dashboard:run:complete',
  () => updateState('#dashboard-state', 'Done')
)

Anda menyelesaikan dengan mem-build elemen yang disematkan:

.build()

Menghubungkan ke konten yang disematkan

Jika ingin mengirim pesan ke dan menerima pesan dari elemen yang disematkan, Anda perlu memanggil connect(), yang menampilkan Promise yang akan di-resolve ke antarmuka komunikasi elemen yang diberikan:

.connect()
.then(setupDashboard)
.catch(console.error)

Membuat URL untuk SDK

Dokumentasi utama untuk URL sematan yang ditandatangani Looker ada di halaman dokumentasi Penyematan yang ditandatangani. Satu-satunya perbedaan saat membuat URL untuk SDK adalah Anda harus menambahkan parameter sdk=2 ke URL sematan bersama parameter lain, seperti filter dan parameter embed_domain. Parameter ini memungkinkan Looker menentukan apakah SDK ada dan memanfaatkan fitur tambahan yang disediakan oleh SDK. Contoh:

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
                                                 ^^^^^^

SDK tidak dapat menambahkan parameter ini sendiri karena parameter tersebut merupakan bagian dari URL sematan yang ditandatangani.

Endpoint autentikasi

Karena rahasia penyematan perlu dijaga dengan cermat, URL sematan yang ditandatangani tidak dapat dibuat di browser. Untuk mempermudah dan mengamankan prosesnya, Anda dapat mengikuti langkah-langkah berikut:

Terapkan fungsi penandatanganan URL di server web Anda. Server harus menampilkan URL yang ditandatangani menggunakan salah satu proses yang didokumentasikan dalam repositori GitHub Contoh SSO Tersemat Looker.
Teruskan URL sematan yang ditandatangani ke endpoint penandatanganan tersebut di Embed SDK. Lokasi endpoint ditentukan oleh parameter authUrl di LookerEmbedSDK.init().

Jika ditentukan, setiap kali elemen sematan dibuat hanya menggunakan ID, URL sematannya akan dibuat menggunakan jenis elemen, host Looker yang disediakan, dan parameter apa pun yang disediakan. Contoh:

LookerEmbedSDK.init('looker.example.com', '/looker_auth')
LookerEmbedSDK.createcreateDashboardWithId(11)
  .build()

Contoh sebelumnya akan memanggil endpoint /looker_auth dan menampilkan URL sematan bertanda tangan yang dapat digunakan untuk membuat konten sematan:

src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

Konfigurasi autentikasi lanjutan

Endpoint autentikasi dapat dikonfigurasi lebih lanjut untuk mengizinkan header permintaan kustom serta dukungan CORS. Anda dapat melakukannya dengan meneruskan objek opsi ke metode init:


LookerEmbedSDK.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
  })

Helper node

Metode helper penandatanganan createSignedUrl() disediakan di server_utils/auth_utils.ts. Penggunaannya adalah sebagai berikut:

import { createSignedUrl } from './auth_utils'

app.get('/looker_auth', function(req, res) {
  // TO DO: Add your code here to authenticate that the request is from a valid user
  const src = req.query.src;
  const host = 'https://looker.example.com'
  const secret = YOUR_EMBED_SECRET
  const user = authenticatedUser
  const url = createSignedUrl(src, user, host, secret);
  res.json({ url });
});

Ini adalah struktur data pengguna:

interface LookerEmbedUser {
  external_user_id: string
  first_name?: string
  last_name?: string
  session_length: number
  force_logout_login?: boolean,
  permissions: LookerUserPermission[]
  models: string[]
  group_ids?: number[]
  external_group_id?: string
  user_attributes?: {[key: string]: any}
  access_filters: {}
}

Parameter access_filters telah dihapus di Looker 3.10, tetapi masih diperlukan dengan placeholder kosong di URL sematan.

Pemecahan masalah

Logging

Embed SDK dibuat di atas 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 = ''