iFrame ve sorgu parametresi ayrıntıları

Classroom eklentileri, son kullanıcıya sorunsuz ve kullanışlı bir kullanıcı deneyimi sunmaktır. RACI matrisinde iframe türleri; Kullanıcı yolculukları dizinindeki iframe'ler sayfalarını her bir iframe'in amacına ve görünümüne genel bakış.

iframe güvenlik yönergeleri

İş ortaklarının, iframe'lerini güvence altına almak için sektördeki en iyi uygulamalardan yararlanmaları beklenir. Güvenlik ekibimiz, iframe'i korumak için aşağıdakileri önerir:

• HTTPS gereklidir. TLS 1.2 veya daha üst bir sürüm kullanılmasını HTTP Strict Transport Security'yi etkinleştirebilirsiniz. Bu ilgili MDN'yi göster başlıklı makaleyi inceleyin.

• Katı İçerik Güvenliği Politikası'nı etkinleştirin. Bu OWASP'a göz atın makalesini ve bu İçerik Güvenliği Politikası MDN makalesini inceleyin.

• Güvenli çerez özelliğini etkinleştirin. HttpOnly özelliğine ve bu ilgili Çerezler MDN makalesi.

iFrame URI yapılandırması

Ek Kurulum URI'si, Attach Discovery iframe'inin yüklediği öğedir ve öğretmenlerin yeni bir Classroom yayını. Google Cloud proje konsolunda ayarlanabilir. Bu URI'yi Google Cloud projenizin API'sinde ayarlayın ve Hizmet > Google Workspace Marketplace SDK'sı > Uygulama Yapılandırması sayfasına gidin.

İzin Verilen Ek URI Ön Ekleri, *.addOnAttachments.create ve özelliklerini kullanarak AddOnAttachment *.addOnAttachments.patch yöntem. Doğrulama, düz bir dize öneki. eşleşiyor ve şu anda joker karakterlerin kullanılmasına izin vermiyor.

Sorgu parametreleri

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

Ekle ilgili parametreler

Ekle ilgili parametreler, eklentiye ait olan ve eklenti eki, öğrencinin ödevi ve yetkilendirme jetonu.

Ders kimliği

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

Tüm iframe'lere dahil edilir.

Öğe Kimliği

itemId değeri, Announcement öğesinin tanımlayıcısıdır

Bu ekin bulunduğu CourseWork veya CourseWorkMaterial ekli.

Tüm iframe'lere dahil edilir.

Öğe Türü

itemType değeri, bu hedefin

ek ekli. İletilen dize değeri şunlardan biri: "announcements" "courseWork" veya "courseWorkMaterials".

Tüm iframe'lere dahil edilir.

Ek kimliği

attachmentId değeri, eke yönelik bir tanımlayıcıdır.

teacherViewUri, studentViewUri ve studentWorkReviewUri iframe.

Gönderim kimliği

submissionId değeri, öğrencinin çalışmasının tanımlayıcısıdır. ancakattachmentId belirli bir ödevle ilgili çalışma.

studentWorkReviewUri ile birlikte sunulur.

'nı inceleyin.

Not: Şu işlemler için submissionId ve attachmentId öğelerinin bileşik anahtarını kullanabilirsiniz: aynı ekin atanması durumunda öğrencinin çalışmasını tanımlama aynı öğrenciyi eğitmek. Daha fazla bilgi için bkz. kopyalanan içerik.

Eklenti jetonu

addOnToken değeri, şunun için kullanılan bir yetkilendirme jetonudur:

addOnAttachments.create eklentisini çağırıyor.

Ek Discovery iframe'ine ve Bağlantı Yeni Sürüme Geçirme'ye dahil edilir. iFrame'i seçin.

Yeni sürüme geçirilecek URL

urlToUpgrade değerinin varlığı,

öğretmen ödeve bir bağlantı eki eklediyse eklenti ekine yükseltin. Henüz yapmadıysanız yapılandırıldıysa, eklenti bağlantılarını yeni sürüme geçirme ile ilgili kılavuza eklerini inceleyin.

Bağlantı Yükseltme iframe'ine dahildir.

Oturum açmayla ilgili parametreler

login_hint sorgu parametresi, Eklenti web sayfasını ziyaret eden Classroom kullanıcısı. Bu sorgu parametresi değeri, iframe src URL'sinde sağlanır. Kullanıcı daha önce son kullanıcıların oturum açma sorunlarını azaltmaya yardımcı olması için eklentinizi kullanmanızı öneririz. Sizden bu sorgu parametresini kullanabilirsiniz.

Giriş ipucu

login_hint, kullanıcının Google adresi için benzersiz bir tanımlayıcıdır

Hesap'a dokunun. Kullanıcı, eklentinize ilk kez giriş yaptıktan sonra Eklentinize yapılan her sonraki ziyarette login_hint parametresi, ekleyebilirsiniz.

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

1. Kimlik doğrulama akışı sırasında login_hint değerini ileterek Oturum açma iletişim kutusunda kimlik bilgilerini girmesine gerek yoktur görünür. Kullanıcının oturumu otomatik olarak açılmamıştır.
2. Kullanıcı oturum açtıktan sonra, bu parametreyi kullanarak eklentide oturum açmış olabilecek tüm kullanıcılara gösterilir. Eğer bir eşleşme bulduğunuzda, kullanıcıyı oturum açmış olarak bırakabilir ve hoş geldiniz. Parametre, oturum açtığınız girişlerle eşleşmiyorsa oturum açmak için, kullanıcıdan Google markalı bir oturum açma düğmesini tıklayın.

Tüm iframe'lere dahil edilir.

'nı inceleyin.

Not: login_hint şartlarını uygulama hakkında ek bilgiler edinebilirsiniz parametresini ve SSO, Sorunsuz oturum açma ve İşleyici'deki oturum açma akışı tekrar eden giriş bölümü sayfaları oluşturun.

Ek Bulma iframe'i

Boyut	Açıklama
Zorunlu	Evet
URI	Eklenti meta verisinde sağlanır
Sorgu Parametreleri	courseId, itemId, itemType, addOnToken ve login_hint.
Boy	Üst başlık için% 80 pencere yüksekliği eksi 60 piksel
Genişlik	Pencere <= 600 piksel olduğunda maksimum 1.600 piksel % 90 pencere genişliği geniş Pencere yapıldığında pencere genişliğinin% 80'i > 600 piksel genişlik

Örnek Ek Keşfi senaryosu

1. Google Workspace'e kayıtlı bir Classroom eklentisi Ek Keşif URI'si https://example.com/addon olan pazar yeri.
2. Bir öğretmen bu eklentiyi yükler ve yeni bir duyuru, ödev veya ödev oluşturur tek bir kursa dahil etmelisiniz. Örneğin, itemId=234, itemType=courseWork ve courseId=123.
3. Öğretmen, öğeyi yapılandırırken yeni yüklenen eklentiyi seçer ekleyebilirsiniz.
4. Classroom, src URL'si şu şekilde bir iframe oluşturur: https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
   1. Öğretmen, ek seçimi yapmak için iframe içinde çalışır.
5. Ek seçiminde eklenti, şuna bir postMessage gönderir: Classroom'u kapatın.

öğretmenViewUri vestudentViewUri iframe'leri

Boyut	Açıklama
Zorunlu	Evet
URI	teacherViewUri veya studentViewUri
Sorgu Parametreleri	courseId, 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
Zorunlu	Hayır (Bunun etkinlik türünde bir ek olup olmadığını belirler)
URI	studentWorkReviewUri
Sorgu Parametreleri	courseId, 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 312 piksel genişletildiğinde 56 piksel, daraltıldığında 56 piksel

Not: Öğretmenler, Öğrenci Çalışması İnceleme iFrame'ini şu koşulları karşılayan bir öğrenci için açabilir: kullanıcı eklenti ekini daha önce görüntülemedi. Bu durumda eklenti bu öğrenciden haberdar değildir ve uygun bir mesaj gösterir.

Bağlantı Yükseltme iframe'i

Boyut	Açıklama
Zorunlu	Evet, eklenti eklerine bağlantıları yeni sürüme geçirme durumunda ve eklentiniz tarafından desteklenir.
URI	Eklenti meta verisinde sağlanır
Sorgu Parametreleri	courseId, itemId, itemType, addOnToken, urlToUpgrade ve login_hint.
Boy	Üst başlık için% 80 pencere yüksekliği eksi 60 piksel
Genişlik	Pencere <= 600 piksel olduğunda maksimum 1.600 piksel % 90 pencere genişliği geniş Pencere yapıldığında pencere genişliğinin% 80'i > 600 piksel genişlik

Bağlantı Yeni Sürüme Geçme senaryosu örneği

1. Bir Classroom eklentisi, aşağıdaki gibi bir Bağlantı Yükseltme URI'si ile kaydedilmiştir: https://example.com/upgrade Aşağıdaki ana makineyi ve yolu sağladınız Bağlantı ekleri için Classroom'un kullanması gereken önek kalıpları eklenti ekine yükseltmeyi deneyin:
   • Ana makine example.com, yol öneki ise /quiz şeklindedir.
2. Bir öğretmen, takip edebilirsiniz. Örneğin itemId=234, itemType=courseWork ve courseId=123.
3. Bir öğretmen, bağlantıya (https://example.com/quiz/5678) bir bağlantı yapıştırır sağladığınız URL kalıbıyla eşleşen ek iletişim kutusu. Öğretmen ve ardından bağlantıyı bir eklenti ekine yükseltmeniz istendi.

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

5. iframe'de iletilen sorgu parametrelerini değerlendirir ve CreateAddOnAttachment uç noktası. urlToUpgrade sorgusunun parametresi, iframe'e geçirildiğinde URI olarak kodlanır. parametresini orijinal biçiminde alabilirsiniz. JavaScript örneğin, decodeURIComponent() işlevini kullanın.

6. Bir Bağlantı'dan eklenti eki başarıyla oluşturulduğunda, iframe'i kapatmak için Classroom'a postMessage.

iframe'i kapat

iframe, öğrenme aracından şunu içeren bir postMessage gönderilerek kapatılabilir: {type: 'Classroom', action: 'closeIframe'} yükü. Classroom, bu postMessage öğesini yalnızca ana_makine_adı+bağlantı noktasından kabul ediyor açılan orijinal URI'ya karşılık gelir.

<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ı aynı olmalıdır. iframe'i başlatmak için kullanılan URI'nınki şeklinde alan+bağlantı noktası, aksi takdirde ileti yok sayılır. Geçici çözüm, orijinal alandaki bir sayfaya geri yönlendirmektir. postMessage etkinliğini göndermekten başka bir şey yapmaz.

iframe'i yeni sekmeden kapatma

Alanlar arası korumalar bunun çalışmasını engeller. Geçici çözüm, iframe ile yeni sekme arasındaki iletişimi kendiniz denetlemenizi ve iframe'in nihayetinde kapanış postMessage etkinliğini düzenlemekten sorumludur. Yan olarak "İş Ortağı Adı'nda Aç" köprüsüne dikkat edin. kaldırılacağından, bu bu şekilde sekme oluşturabilirsiniz.

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ı

• allow="microphone *"

Üçüncü taraf çerezlerini engelleme

Üçüncü taraf çerezlerini engellemenin bir IP adresini değiştirmeyi zorlaştırdığını unutmayın. iframe'de oturum açık. https://www.cookiestatus.com adresine farklı tarayıcılarda çerez engellemenin mevcut durumu Tabii ki bu Bu sorun, Google Classroom eklentilerine özel değildir ve iframe üçüncü taraflarını kullanır. İş ortaklarımızın çoğu bu sorunla daha önce karşılaşmıştır.

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

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

Gelecekteki tarayıcı sürümlerinde daha fazla çerez kısıtlaması olması bekleniyor. İçerik üretme Gereken artışın nasıl azaltılacağıyla ilgili Google'a geri bildirim göndermek için özellik istekleri elde etti.

URL normal ifadelerini kullanarak eklentilerin bulunabilirliğini etkinleştir

Öğretmenler sıklıkla bağlantı ekleri olan ödevler oluşturur. Kullanımı teşvik etmek olmak istiyorsanız, kaynakların URL'leriyle eşleşen normal ifadeler bu bilgilere erişebilirsiniz. Bir öğretmenin eşleşen bir bağlantıyı eklemesi normal ifadelerinizin, onları denemeye teşvik eden kapatılabilir bir iletişim kutusu görmesi ekleyebilirsiniz. Yalnızca ilgili eklentinin yüklü olduğu durumlarda iletişim kutusunu görürler. giriş yapmış olabilir.

Bu davranışı öğretmenlere de uygulamak istiyorsanız Google kişilere ulaşabilirsiniz. Normal ifadeler başka bir eklentiyle çakışıyorsa veya başka bir eklentiyle çakışıyorsa, olacak şekilde değiştirilmiştir.

Şekil 1. Bağlantı seçen öğretmen ekleyebilirsiniz.

Şekil 2. Öğretmen üçüncü taraftan bağlantı yapıştırma kaynak. Öğretmen zaten üçüncü taraf bir Classroom eklentisi.

Şekil 3. Sunulan etkileşimli iletişim kutusu tarafından belirtilen normal ifadeyle eşleştiğinde, öğretmene üçüncü taraf geliştiriciye gönderilir.

Bir öğretmen "Şimdi deneyin"i seçerse Şekil 3'te görüldüğü gibi, pop-up'ları eklentinizin Ek Discovery iframe'ine yönlendirilir.