AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-iframe

 
You can now use this component outside valid AMP documents using the Bento version of this component. Learn more in the Bento guide.

Description

Displays an iframe.

 

Required Scripts

<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>

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 Didukung fill, fixed, fixed-height, flex-item, intrinsic, nodisplay, responsive
Contoh Contoh 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

src Atribut 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, referrerpolicy Semua atribut ini berperilaku dengan cara yang sama seperti pada iframe standar.
Jika frameborder tidak ditentukan, secara default, nilainya akan ditetapkan ke 0.
sandbox iframe 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 umum Elemen 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?

Anda telah membaca dokumen ini belasan kali, tetapi belum semua pertanyaan Anda terjawab? Mungkin orang lain merasakan hal yang sama. Berinteraksilah dengan mereka di Stack Overflow.

Kunjungi Stack Overflow
Menemukan bug atau ada fitur yang kurang?

Proyek AMP sangat menganjurkan partisipasi dan kontribusi Anda! Kami berharap Anda akan terus ambil bagian dalam komunitas sumber terbuka kami, tetapi kami juga menerima kontribusi satu kali untuk topik tertentu yang Anda minati.

Kunjungi GitHub