amp-iframe

1.0 0.1

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

Menampilkan 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:

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

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.