AMP

amp-iframe

Menampilkan iframe.

Skrip yang Diperlukan<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
Tata Letak yang Didukungfill, fixed, fixed-height, flex-item, intrinsic, nodisplay, responsive
ContohContoh kode beranotasi untuk amp-iframe

Perilaku

amp-iframe memiliki beberapa perbedaan penting dibandingkan iframe vanilla yang dirancang untuk menjadikannya lebih aman dan menghindari file AMP yang didominasi oleh iframe tunggal:

  • amp-iframe tidak akan muncul di dekat bagian atas dokumen (kecuali untuk iframe yang menggunakan placeholder seperti dijelaskan di bawah). iframe harus berjarak 600 piksel dari atas, atau tidak dalam 75% pertama dari viewport saat di-scroll ke atas, salah satu yang lebih kecil.
  • Secara default, amp-iframe ditempatkan dalam sandbox (lihat detail).
  • amp-iframe hanya boleh meminta resource melalui HTTPS, dari data-URI, atau melalui atribut srcdoc.
  • amp-iframe tidak boleh berada dalam asal yang sama dengan container kecuali jika allow-same-origin tidak diizinkan dalam atribut sandbox. Lihat dokumen “Kebijakan asal iframe” untuk penjelasan selengkapnya mengenai asal yang diizinkan untuk iframe.

Contoh: Menyematkan Google Map di dalam amp-iframe

<amp-iframe width="200" height="100"
    sandbox="allow-scripts allow-same-origin"
    layout="responsive"
    frameborder="0"
    src="https://www.google.com/maps/embed/v1/place?key=AIzaSyDG9YXIhKBhqclZizcSzJ0ROiE0qgVfwzI&q=iceland">
  </amp-iframe>

Dirender sebagai:

Untuk melihat demo amp-iframe lainnya, buka AMP By Example.

Penggunaan amp-iframe untuk iklan

amp-iframe tidak boleh digunakan dengan maksud utama untuk menampilkan iklan. Anda BOLEH menggunakan amp-iframe untuk menampilkan video, di mana bagian dari video tersebut merupakan iklan. Kebijakan AMP ini dapat diberlakukan dengan tidak merender iframe yang terkait.

Untuk kasus penggunaan iklan, gunakan amp-ad.

Alasan penggunaan kebijakan ini adalah:

  • amp-iframe memberlakukan sandboxing dan sandbox juga diterapkan pada iframe turunan. Artinya, halaman landing mungkin rusak, meskipun iklan itu sendiri tampak berfungsi.
  • amp-iframe tidak menyediakan mekanisme apa pun untuk meneruskan konfigurasi ke iframe.
  • amp-iframe tidak memiliki mekanisme pengubahan ukuran terkontrol iframe sepenuhnya.
  • Informasi visibilitas mungkin tidak tersedia untuk amp-iframe.

Atribut

srcAtribut src berperilaku sangat mirip dengan iframe standar dengan satu pengecualian: fragmen #amp=1 ditambahkan ke URL untuk memberi tahu dokumen sumber bahwa ia disematkan dalam konteks AMP. Fragmen ini hanya akan ditambahkan jika URL yang ditentukan oleh src belum memiliki fragmen.
srcdoc, frameborder, allowfullscreen, allowpaymentrequest, allowtransparency, referrerpolicySemua atribut ini berperilaku dengan cara yang sama seperti pada iframe standar.
Jika frameborder tidak ditentukan, secara default, nilainya akan ditetapkan ke 0.
sandboxiframe yang dibuat oleh amp-iframe selalu memiliki atribut sandbox yang ditentukan. Secara default, nilainya adalah kosong, yang berarti bahwa nilai tersebut adalah "nilai maksimum sandbox". Dengan menetapkan nilai sandbox, pengguna dapat memilih agar iframe tidak terlalu diamankan dalam sandbox. Semua nilai yang didukung oleh browser diizinkan. Contohnya, menetapkan sandbox="allow-scripts" akan memungkinkan iframe menjalankan JavaScript, atau sandbox="allow-scripts allow-same-origin" akan memungkinkan iframe menjalankan JavaScript, membuat non-CORS XHR, dan membaca/menulis cookie.

Jika Anda membingkai dokumen dengan iframe yang tidak dibuat secara khusus dengan memperhatikan penerapan sandbox, besar kemungkinan Anda harus menambahkan allow-scripts allow-same-origin ke atribut sandbox dan mungkin perlu mengizinkan kemampuan tambahan.

Perhatikan juga bahwa sandbox berlaku untuk semua jendela yang dibuka dari iframe dalam sandbox. Ini termasuk jendela baru yang dibuat oleh link dengan target=_blank (tambahkan allow-popups untuk memungkinkan terjadinya hal ini). Dengan menambahkan allow-popups-to-escape-sandbox ke atribut sandbox, jendela baru tersebut akan berperilaku seperti jendela baru yang tidak berada dalam sandbox. Kemungkinan besar inilah perilaku yang Anda inginkan dan harapkan. Sayangnya, pada saat penulisan artikel ini, allow-popups-to-escape-sandbox hanya didukung oleh Chrome.

Lihat dokumen di MDN untuk penjelasan selengkapnya mengenai atribut sandbox.
atribut umumElemen ini mencakup atribut umum yang diperluas ke komponen AMP.

iframe dengan placeholder

Anda dapat memunculkan amp-iframe di bagian atas dokumen jika amp-iframe memiliki elemen placeholder seperti ditunjukkan pada contoh di bawah.

  • amp-iframe harus memuat elemen dengan atribut placeholder, (misalnya elemen amp-img) yang akan dirender sebagai placeholder sampai iframe siap ditampilkan.
  • Kesiapan iframe dapat diketahui dengan mendeteksi onload iframe atau embed-ready postMessage, yang akan dikirim oleh dokumen iframe, salah satu yang terjadi lebih dahulu.

Contoh: iframe dengan placeholder

<amp-iframe width=300 height=300
    layout="responsive"
    sandbox="allow-scripts allow<-same-origin"
    src="https://foo.com/iframe"
    <amp-img layout="fill" src="https://foo.com/foo.png" placeholder></amp-img>
</amp-iframe>

Contoh: Permintaan iframe siap disematkan

window.parent.postMessage({
  sentinel: 'amp',
  type: 'embed-ready'
  }, '*');

Pengubahan ukuran iframe

amp-iframe harus menggunakan tata letak statis seperti halnya elemen AMP lainnya. Namun, Anda dapat mengubah ukuran amp-iframe saat runtime. Untuk melakukannya:

  1. amp-iframe harus ditetapkan dengan atribut resizable.
  2. amp-iframe harus memiliki elemen turunan overflow.
  3. amp-iframe harus menetapkan atribut sandbox allow-same-origin.
  4. Dokumen iframe harus mengirimkan permintaan embed-size sebagai pesan jendela.
  5. Permintaan embed-size akan ditolak jika tinggi permintaan kurang dari ambang batas tertentu (100 piksel).

Perhatikan bahwa resizable mengganti nilai scrolling ke no.

Contoh: amp-iframe dengan elemen overflow

<amp-iframe width=300 height=300
    layout="responsive"
    sandbox="allow-scripts allow-same-origin"
    resizable
    src="https://foo.com/iframe">
    <div overflow tabindex=0 role=button aria-label="Read more">Read more!</div>
</amp-iframe>

Contoh: permintaan pengubahan ukuran iframe

window.parent.postMessage({
  sentinel: 'amp',
  type: 'embed-size',
  height: document.body.scrollHeight
  }, '*');

Setelah pesan ini diterima, AMP runtime akan mencoba mengakomodasi permintaan tersebut sesegera mungkin, tetapi dengan memperhitungkan di mana pembaca sedang membaca, apakah scroll sedang berlangsung, dan faktor UX atau performa lainnya. Jika runtime tidak dapat memenuhi permintaan pengubahan ukuran, amp-iframe akan menampilkan elemen overflow. Mengklik elemen overflow akan langsung mengubah ukuran amp-iframe karena dipicu oleh tindakan pengguna.

Berikut ini beberapa faktor yang memengaruhi seberapa cepat pengubahan ukuran akan dieksekusi:

  • Apakah pengubahan ukuran dipicu oleh tindakan pengguna.
  • Apakah pengubahan ukuran diminta untuk iframe yang sedang aktif.
  • Apakah pengubahan ukuran diminta untuk iframe yang berada di bawah, atau di atas viewport.

Visibilitas iframe

iframe dapat mengirim pesan send-intersections kepada induknya agar mulai menerima catatan perubahan gaya IntersectionObserver untuk intersection iframe dengan viewport induk.

Catatan: Dalam contoh berikut, kami menganggap skrip berada dalam iframe yang dibuat, dengan window.parent menjadi jendela paling atas. Jika skrip berada di iframe bertingkat, ubah window.parent ke jendela AMP paling atas.

Contoh: permintaan send-intersections iframe

window.parent.postMessage({
  sentinel: 'amp',
  type: 'send-intersections'
  }, '*');

iframe dapat mendeteksi pesan intersection dari jendela induk untuk menerima data intersection.

Contoh: permintaan send-intersections iframe

window.addEventListener('message', function(event) {
  if (event.source != window.parent ||
  event.origin == window.location.origin ||
  !event.data ||
  event.data.sentinel != 'amp' ||
  event.data.type != 'intersection') {
    return;
    }
  event.data.changes.forEach(function (change) {
    console.log(change);
  });
});

Pesan intersection akan dikirim oleh induk ke iframe saat iframe bergerak masuk atau keluar dari viewport (atau terlihat sebagian), ketika iframe di-scroll atau diubah ukurannya.

iframe pelacakan/analisis

Kami sangat merekomendasikan penggunaan amp-analytics untuk keperluan analisis, karena solusi ini jauh lebih tangguh, lengkap, dan efisien yang dapat dikonfigurasi untuk berbagai vendor analisis.

AMP hanya mengizinkan satu iframe yang digunakan untuk keperluan pelacakan dan analisis, per halaman. Untuk menghemat resource, iframe ini akan dihapus dari DOM 5 detik setelah dimuat, yang mestinya cukup untuk menyelesaikan pekerjaan apa pun yang perlu dilakukan.

iframe diidentifikasi sebagai iframe pelacakan/analisis jika tampaknya tidak memiliki kegunaan pengguna langsung apa pun, misalnya iframe yang tidak terlihat atau kecil.

Panduan: Prioritaskan komponen AMP yang ada daripada amp-iframe

Komponen amp-iframe harus dianggap sebagai fallback jika pengalaman pengguna yang diperlukan tidak dimungkinkan melalui cara lain di AMP; artinya, belum ada komponen AMP untuk kasus penggunaan itu. Hal ini karena ada banyak manfaat dari penggunaan komponen AMP yang disesuaikan dengan kasus penggunaan tertentu seperti:

  • Pengelolaan dan performa resource yang lebih baik
  • Pada kasus tertentu, komponen kustom dapat memberikan gambar placeholder built-in. Dengan begitu pengguna dapat, misalnya, mendapatkan thumbnail video yang tepat sebelum video dimuat, dan mengurangi upaya coding untuk menambahkan placeholder secara manual.
  • Pengubahan ukuran built-in. Hal ini berarti konten iframe dengan ukuran yang tidak dapat diprediksi dapat ditampilkan lebih sering kepada pengguna seolah-olah konten tersebut native untuk halaman itu, bukan dalam frame yang dapat di-scroll
  • Fitur tambahan lainnya dapat tersedia secara built-in (misalnya, fitur autoplay untuk pemutar video)

Validasi

Lihat aturan amp-iframe dalam spesifikasi validator AMP.

Perlu bantuan lainnya?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub