iFrame ve sorgu parametresi ayrıntıları

Classroom eklentileri, son kullanıcıya sorunsuz ve kullanışlı bir kullanıcı deneyimi sağlamak için iframe içinde yüklenir. Dört farklı iframe türü vardır. Her bir iframe'in amacı ve görünümüne genel bir bakış için Kullanıcı yolculukları dizinindeki iframes sayfalarına bakın.

iframe güvenlik kuralları

İş ortaklarının iframe'lerini güvence altına almak için sektördeki en iyi uygulamaları takip etmesi beklenir. iframe'i korumak için güvenlik ekibimiz şunları öneriyor:

• HTTPS gereklidir. TLS 1.2 veya daha yeni bir sürüm kullanmanızı ve HTTP Strict Transport Security'yi etkinleştirmenizi kesinlikle öneririz. Katı Taşıma Güvenliği ile ilgili bu ilgili MDN makalesine bakın.

• Yüksek Düzeyli İçerik Güvenliği Politikası'nı etkinleştirin. Bu OWASP makalesini ve ilgili İçerik Güvenliği Politikası MDN makalesini inceleyin.

• Güvenli çerez özelliğini etkinleştirin. HttpOnly özelliği ve ilgili Cookies MDN makalesine bakın.

iFrame URI yapılandırması

Ek Kurulum URI'sı, Ek Keşfi iframe'inin yüklendiği yerdir ve öğretmenler Classroom yayınında eklenti ekleri oluşturma akışına başlar. Google Cloud proje konsolunda ayarlanabilir. Bu URI'yi Google Cloud projenizin API ve Hizmeti > Google Workspace Marketplace SDK'sı > Uygulama Yapılandırması sayfasında ayarlayın.

İzin Verilen Ek URI'sı Önekleri, *.addOnAttachments.create ve *.addOnAttachments.patch yöntemleri kullanılarak AddOnAttachment'ta ayarlanan URI'leri doğrulamak için kullanılır. Doğrulama, dizenin ön ek eşleşmesidir ve şu anda joker karakterlerin kullanılmasına izin vermez.

Sorgu parametreleri

iframe'ler, kritik bilgileri eklentiye sorgu parametreleri olarak iletir. İki parametre kategorisi vardır: ekle ve oturum açmayla ilgili parametreler.

Eklerle ilgili parametreler

Ekle ilgili parametreler eklentiye kurs, ödev, eklenti eki, öğrencinin gönderimi ve yetkilendirme jetonu hakkında bilgiler sağlar.

Kurs Kimliği

courseId değeri, ders için kullanılan bir tanımlayıcıdır.

Tüm iframe'lere dahildir.

Yayın Kimliği (kullanımdan kaldırıldı)

postId değeri, bu ekin eklendiği yayının (duyuru, sınıf çalışması veya sınıf çalışması materyali) tanımlayıcısıdır.

Tüm iframe'lere dahildir.

Kullanımdan kaldırıldı: Yayın kimliği kullanımdan kaldırıldı. Bunun yerine Öğe Kimliği'ni kullanın.

Öğe Kimliği

itemId değeri, bu ekin eklendiği Announcement, CourseWork veya CourseWorkMaterial tanımlayıcısıdır.

Tüm iframe'lere dahildir.

Öğe Türü

itemType değeri, bu ekin eklendiği kaynak türünü tanımlar. İletilen dize değeri "announcements", "courseWork" veya "courseWorkMaterials" değerlerinden biri.

Tüm iframe'lere dahildir.

Ek Kimliği

attachmentId değeri, ek için bir tanımlayıcıdır.

teacherViewUri, studentViewUri ve studentWorkReviewUri iframe'lere dahildir.

Gönderim kimliği

submissionId değeri, öğrencinin çalışmasının tanımlayıcısıdır ancak öğrencinin belirli bir ödevdeki çalışmasını tanımlamak için attachmentId ile birlikte kullanılmalıdır.

studentWorkReviewUri ile sunulur.

Not: Aynı ekin farklı derslerde aynı öğrenciye atanmış olması durumunda, öğrencinin çalışmasını tanımlamak için submissionId ve attachmentId öğelerinin birleşik anahtarını kullanabilirsiniz. Daha fazla bilgi için kopyalanan içerik bölümünü inceleyin.

Eklenti jetonu

addOnToken değeri, eklentiyi oluşturmak amacıyla addOnAttachments.create çağrıları yapmak için kullanılan bir yetkilendirme jetonudur.

Ek Keşfetme iframe'i ve Bağlantı Yükseltme iframe'i ile birlikte sunulur.

Yeni sürüme geçirilecek URL

urlToUpgrade değerinin varlığı, öğretmenin ödeve bir Bağlantı eki eklediği ve bunu bir eklenti ekine yükseltmeyi kabul ettiği anlamına gelir. Bu özelliği henüz yapılandırmadıysanız daha ayrıntılı bilgi için bağlantıları eklenti eklerine yükseltme hakkındaki kılavuza bakın.

Bağlantı Yükseltme iframe'i ile birlikte sunulur.

Oturum açmayla ilgili parametreler

login_hint sorgu parametresi, eklenti web sayfasını ziyaret eden Classroom kullanıcısı hakkında bilgi sağlar. Bu sorgu parametresi, iframe src URL'sinde sağlanır. Son kullanıcının oturum açma sorunlarını azaltmaya yardımcı olması için kullanıcı daha önce eklentinizi kullandığında gönderilir. Bu sorgu parametresini eklenti uygulamanızda işlemeniz gerekir.

Giriş ipucu

login_hint, kullanıcının Google hesabına ait benzersiz bir tanımlayıcıdır

Hesap'a dokunun. Kullanıcı, eklentinize ilk kez giriş yaptıktan sonra aynı kullanıcı tarafından eklentinize yapılan sonraki her ziyarette login_hint parametresi aktarılır.

login_hint parametresinin iki olası kullanımı vardır:

1. Oturum açma iletişim kutusu açıldığında kullanıcının kimlik bilgilerini girmesine gerek kalmaması için kimlik doğrulama akışı sırasında login_hint değerini iletin. Kullanıcı otomatik olarak oturum açmaz.
2. Kullanıcı oturum açtıktan sonra değeri, eklentide zaten oturum açmış olabilecek kullanıcılarla karşılaştırmak için bu parametreyi kullanın. Bir eşleşme bulursanız kullanıcının oturumunu açık bırakabilir ve oturum açma akışı görüntülenmemesini sağlayabilirsiniz. Parametre, oturum açmış kullanıcılarınızdan hiçbiriyle eşleşmiyorsa kullanıcıdan Google markalı oturum açma düğmesi ile oturum açmasını isteyin.

Tüm iframe'lere dahildir.

Not: TOA, Sorunsuz oturum açma ve Tekrarlı giriş incelemelerini yönetme sayfalarında login_hint parametresini ve oturum açma akışını uygulama hakkında daha fazla bilgi bulabilirsiniz.

Ek Keşfi iframe'i

Boyut	Açıklama
Gerekli	Evet
URI	Eklenti meta verilerinde sağlanır
Sorgu Parametreleri	courseId, postId (kullanımdan kaldırıldı), itemId, itemType, addOnToken ve login_hint.
Boy	Üst başlık için% 80 pencere yüksekliği eksi 60 piksel
Genişlik	Maksimum 1.600 piksel Pencere <= 600 piksel genişliğinde olduğunda% 90 pencere genişliği Pencere genişliği 600 pikselden büyük olduğunda pencere genişliği% 80

Örnek Ek Keşfi senaryosu

1. Bir Classroom eklentisi Google Workspace Marketplace'te https://example.com/addon olan Ek Keşif URI'sı ile kayıtlıdır.
2. Öğretmen bu eklentiyi yükler ve derslerinden birinde yeni bir duyuru, ödev veya materyal oluşturur. Örneğin, itemId=234, itemType=courseWork ve courseId=123.
3. Öğretmen bu öğeyi yapılandırırken yeni yüklenen eklentiyi ek olarak seçer.
4. Classroom, src URL'si https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 olarak ayarlanmış bir iframe oluşturur.
   1. Öğretmen, iframe içinde bir ek seçimi yapar.
5. Ek seçildiğinde eklenti, iframe'i kapatmak için Classroom'a bir postMessage gönderir.

öğretmenViewUri vestudentViewUri iframe'leri

Boyut	Açıklama
Gerekli	Evet
URI	teacherViewUri veya studentViewUri
Sorgu Parametreleri	courseId, postId (kullanımdan kaldırıldı), itemId, itemType, attachmentId ve login_hint.
Boy	Üst başlık için% 100 pencere yüksekliği eksi 140 piksel
Genişlik	%100 pencere genişliği

öğrenciWorkReviewUri iframe'i

Boyut	Açıklama
Gerekli	Hayır (Bunun etkinlik türünde bir ek olup olmadığını belirler)
URI	studentWorkReviewUri
Sorgu Parametreleri	courseId, postId (kullanımdan kaldırıldı), itemId, itemType, attachmentId, submissionId ve login_hint.
Boy	Üst başlık için% 100 pencere yüksekliği eksi 168 piksel
Genişlik	%100 pencere genişliği eksi kenar çubuğu genişliği<> kenar çubuğu genişletildiğinde 312 piksel, daraltıldığında ise 56 pikseldir

Not: Öğretmenler, daha önce eklenti ekini görüntülememiş olan öğrenciler için Öğrenci Çalışması İnceleme iframe'ini açabilir. Bu durumda, eklenti henüz bu öğrenciden haberdar olmayabilir ve uygun bir mesaj göstermesi gerekir.

Bağlantı Yükseltme iframe'i

Boyut	Açıklama
Gerekli	Evet, bağlantıları eklenti eklerine yükseltme eklentisi tarafından destekleniyorsa kullanılabilir.
URI	Eklenti meta verilerinde sağlanır
Sorgu Parametreleri	courseId, postId (kullanımdan kaldırıldı), itemId, itemType, addOnToken, urlToUpgrade ve login_hint.
Boy	Üst başlık için% 80 pencere yüksekliği eksi 60 piksel
Genişlik	Maksimum 1.600 piksel Pencere <= 600 piksel genişliğinde olduğunda% 90 pencere genişliği Pencere genişliği 600 pikselden büyük olduğunda pencere genişliği% 80

Bağlantı Yeni Sürüme Geçiş için örnek senaryo

1. Bir Classroom eklentisi, https://example.com/upgrade kimlikli Bağlantı Yükseltme URI'sı ile kaydedilir. Classroom'un eklenti ekine yükseltmeyi denemesi gereken Bağlantı ekleri için aşağıdaki ana makine ve yol önek kalıplarını sağladınız:
   • Ana makine example.com ve yol öneki /quiz şeklindedir.
2. Bir öğretmen, derslerinden birinde yeni bir duyuru, ödev veya materyal oluşturur. Örneğin, itemId=234, itemType=courseWork ve courseId=123.
3. Öğretmen, sağladığınız URL kalıbıyla eşleşen Bağlantı eki iletişim kutusuna https://example.com/quiz/5678 bağlantısını yapıştırır. Ardından, öğretmenden Link'i bir eklenti ekine yükseltmesi istenir.

4. Classroom, Bağlantı Yükseltme iframe'ini URL'si https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 olacak şekilde başlatır.

5. iFrame'de iletilen sorgu parametrelerini değerlendirir ve CreateAddOnAttachment uç noktasına bir çağrı yaparsınız. urlToUpgrade sorgu parametresinin, iframe üzerinden iletildiğinde URI kodlu olduğunu unutmayın. Parametreyi orijinal biçiminde elde etmek için kodunu çözmeniz gerekir. Örneğin JavaScript, decodeURIComponent() işlevini sunar.

6. Bir Bağlantıdan eklenti eki başarıyla oluşturulduktan sonra, iframe'i kapatmak için Classroom'a bir postMessage gönderirsiniz.

iframe'i kapatma

iframe, {type: 'Classroom', action: 'closeIframe'} yüküyle bir postMessage göndererek öğrenme aracından kapatılabilir. Classroom, bu postMessage öğesini yalnızca açılan orijinal URI'ye karşılık gelen sunucu_adı+bağlantı noktasından kabul eder.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

iframe'i iframe'den kapatma

postMessage etkinliğini gönderen sayfanın alan adı+bağlantı noktası, iframe'i başlatmak için kullanılan URI'yla aynı alan adı+bağlantı noktasına sahip olmalıdır. Aksi takdirde, mesaj yoksayılır. Geçici bir çözüm, postMessage etkinliğini göndermekten başka bir görevi olmayan orijinal alan adındaki bir sayfaya geri yönlendirmektir.

iframe'i yeni bir sekmeden kapatma

Alanlar arası korumalar bunun çalışmasını engeller. Geçici bir çözüm, iframe ve yeni sekme arasındaki iletişimi kendiniz yönetmek ve close postMessage etkinliğini yayınlamaktan nihai olarak iframe'in sorumlu olmasına izin vermektir. Ayrıca, kullanıcıların yakın gelecekte bu yöntemle sekme oluşturmaması için "İş Ortağı Adı'nda Aç" köprüsü kaldırılıyor.

Kısıtlamalar

Tüm iframe'ler, aşağıdaki korumalı alan özellikleriyle açılır:

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

ve aşağıdaki özellik politikasına

• allow="microphone *"

Üçüncü taraf çerezlerini engelleme

Üçüncü taraf çerezlerini engellemenin, iFrame'de oturum açmış bir oturumu sürdürmeyi zorlaştırdığını unutmayın. Farklı tarayıcılarda çerez engellemenin mevcut durumu için https://www.cookiestatus.com adresine bakın. Elbette, bu sorun Google Classroom eklentilerine özgü değildir ve iframe üçüncü taraflarını kullanan tüm web sitelerini etkiler. İş ortaklarımızın çoğu bu sorunla zaten karşılaşmıştır.

Bazı genel geçici çözümler şunlardır:

• Çerezi birinci taraf bağlamında oluşturmak için yeni bir sekme açın. Bazı tarayıcılar, birinci taraf bağlamında oluşturulan çerezlere üçüncü taraf bağlamında erişim izni verir.
• Kullanıcıdan üçüncü taraf çerezlerine izin vermesini isteyin. Bu tüm kullanıcılar için her zaman mümkün olmayabilir.
• Çerezlere dayalı olmayan, tek sayfalık web uygulamaları tasarlayın.

Gelecekteki tarayıcı sürümlerinde daha fazla çerez kısıtlaması olması beklenmektedir. İş ortaklarının gerektirdiği artışın nasıl azaltılacağı konusunda Google'a geri bildirim göndermek için özellik istekleri oluşturun.

URL normal ifadelerini kullanarak eklentilerin keşfedilebilirliğini etkinleştir

Öğretmenler sıklıkla bağlantı ekleri içeren ödevler oluşturur. Eklentinizin kullanımını teşvik etmek için, eklentinizde erişilebilen kaynakların URL'leriyle eşleşen normal ifadeler belirtebilirsiniz. Normal ifadelerinizden biriyle eşleşen bir bağlantı ekleyen bir öğretmen, öğretmeni eklentinizi denemeye teşvik eden kapatılabilir bir iletişim kutusu görür. İletişim kutusunu yalnızca eklenti kendi hesapları için zaten yüklenmişse görürler.

Bu davranışı öğretmenlere sağlamak istiyorsanız Google kişilerinize uygun normal ifadeleri sağlayın. Sağladığınız normal ifadeler aşırı geniş kapsamlıysa veya başka bir eklentiyle çakışıyorsa daha kısıtlı veya farklı olacak şekilde değiştirilebilir.

Şekil 1. Öğretmen yeni bir ödeve bağlantı eklerken.

Şekil 2. Öğretmenin üçüncü taraf kaynaktan bir bağlantı yapıştırması. Öğretmen üçüncü tarafın Classroom eklentisini daha önce yüklemiştir.

Şekil 3. Yapıştırılan bağlantı, üçüncü taraf geliştirici tarafından belirtilen normal ifadeyle eşleştiğinde öğretmene sunulan etkileşimli iletişim kutusu.

Bir öğretmen, Şekil 3'te görüldüğü gibi açılır pencerede"Şimdi deneyin"i seçerse eklentinizin Ek Keşfi iframe'ine yönlendirilir.