iFrame ve sorgu parametresi ayrıntıları

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

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 yeni bir sürüm kullanmanızı ve HTTP Strict Transport Security'yi etkinleştirmenizi önemle tavsiye ederiz. Katı Taşıma Güvenliği hakkındaki bu ilgili MDN makalesini inceleyin.

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

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

iFrame URI yapılandırması

Ek Kurulum URI'si, Attach Discovery iframe'i tarafından yüklenen öğedir ve öğretmenlerin bir Classroom yayınında eklenti ekleri oluşturma akışına başladığı yerdir. Google Cloud proje konsolunda ayarlanabilir. Bu URI'yi, Google Cloud projenizin API ve Hizmet > Google Workspace Marketplace SDK'sı > Uygulama Yapılandırması sayfasından ayarlayın.

İzin Verilen Ek URI Önekleri, *.addOnAttachments.create ve *.addOnAttachments.patch yöntemleri kullanılarak AddOnAttachment içinde ayarlanan URI'ları doğrulamak için kullanılır. Doğrulama, düz bir dize ön eki 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 ilgili ve oturum açmayla ilgili parametreler.

Ekle ilgili parametreler

Ekle ilgili parametreler; eklentiye ders, ödev, eklenti eki, öğrencinin gönderimi ve yetkilendirme jetonu ile ilgili bilgileri sağlar.

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 ekli olduğu CourseWork veya CourseWorkMaterial.

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'lere dahildir.

Gönderim kimliği

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

studentWorkReviewUri ile birlikte sunulur.

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

Eklenti jetonu

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

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

Ek Discovery iframe'ine ve Link Upgrade iframe'ine dahil edilir.

Yeni sürüme geçirilecek URL

urlToUpgrade değerinin varlığı,

öğretmen ödeve bir bağlantı eki eklemiştir ve bu eki eklenti eki olarak yükseltmeyi kabul etmiştir. Bu özelliği halihazırda 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'ine dahildir.

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ı olmak için kullanıcı daha önce eklentinizi kullandığında gönderilir. Eklenti uygulamanızda bu sorgu parametresini işlemeniz gerekir.

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 aynı kullanıcı tarafından eklentinize yapılan her sonraki ziyarette login_hint parametresi aktarılır.

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

1. Oturum açma iletişim kutusu görüntülendiğinde 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ının oturumu otomatik olarak açılmaz.
2. Kullanıcı oturum açtıktan sonra, değeri eklentide oturum açmış kullanıcılarla karşılaştırmak için bu parametreyi kullanın. Bir eşleşme bulursanız kullanıcıyı oturum açmış olarak bırakabilir ve oturum açma akışının gösterilmemesini sağlayabilirsiniz. Parametre, oturum açmış kullanıcılarınızdan hiçbiriyle eşleşmiyorsa kullanıcıdan Google markalı bir oturum açma düğmesiyle oturum açmasını isteyin.

Tüm iframe'lere dahil edilir.

Not: TOA, Sorunsuz oturum açma ve Tekrar eden girişlerle ilgili adım adım açıklamalı kılavuz sayfalarında login_hint parametresini uygulama ve oturum açma akışı hakkında ek bilgiler bulabilirsiniz.

Ek Bulma iframe'i

Boyut	Açıklama
Gerekli	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	Maksimum 1.600 piksel Pencere <= 600 piksel geniş olduğunda% 90 pencere genişliği Pencere > 600 piksel genişlikte% 80 pencere genişliği

Örnek Ek Keşfi senaryosu

1. Google Workspace Marketplace'te bir Classroom eklentisi, https://example.com/addon Ek Keşif URI'si ile kaydedilmiştir.
2. Bir öğ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, ek seçimi yapmak için iframe içinde çalışır.
5. Ek seçiminde eklenti, iframe'i kapatmak için Classroom'a postMessage gönderir.

öğretmenViewUri vestudentViewUri iframe'leri

Boyut	Açıklama
Gerekli	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
Gerekli	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 genişletildiğinde 312 piksel, daraltıldığında 56 pikseldir

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

Bağlantı Yükseltme iframe'i

Boyut	Açıklama
Gerekli	Evet, eklentiniz eklenti eklerine bağlantıları yeni sürüme geçirmeyi destekliyorsa Evet.
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	Maksimum 1.600 piksel Pencere <= 600 piksel geniş olduğunda% 90 pencere genişliği Pencere > 600 piksel genişlikte% 80 pencere genişliği

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

1. Bir Classroom eklentisi, https://example.com/upgrade değerindeki Bağlantı Yükseltme URI'siyle kaydedilmiş. 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, yol öneki ise /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. Bir öğretmen, Bağlantı eki iletişim kutusuna sağladığınız URL kalıbıyla eşleşen bir bağlantı (https://example.com/quiz/5678) yapıştırır. Ardından öğretmenden bağlantıyı yeni bir eklenti ekine yükseltmesi istenir.

4. Classroom, URL https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 olarak ayarlanmış şekilde Bağlantı Yükseltme iframe'ini 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'den geçirildiğinde URI olarak kodlandığını unutmayın. Parametreyi orijinal biçiminde almak için parametrenin kodunu çözmeniz gerekir. Örneğin JavaScript, decodeURIComponent() işlevini sunar.

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

iframe'i kapat

iframe, {type: 'Classroom', action: 'closeIframe'} yüküne sahip bir postMessage gönderilerek öğrenme aracından kapatılabilir. Classroom, bu postMessage işaretini yalnızca, açılan orijinal URI'ye karşılık gelen host_name+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'yle aynı alan adı+bağlantı noktasına sahip olmalıdır. Aksi takdirde mesaj yoksayılır. Geçici bir çözüm olarak, orijinal alanda bulunan ve postMessage etkinliğini göndermekten başka bir şey yapmayan bir sayfaya geri yönlendirilirsiniz.

iframe'i yeni sekmeden kapatma

Alanlar arası korumalar bunun çalışmasını engeller. Geçici bir çözüm olarak, iframe ile yeni sekme arasındaki iletişimi kendiniz halledebilir ve kapanış postMessage etkinliğini yayınlamaktan nihai olarak iframe'in sorumlu olmasına izin verebilirsiniz. Kullanıcıların yakın gelecekte bu şekilde 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ı

• allow="microphone *"

Üçüncü taraf çerezlerini engelleme

Üçüncü taraf çerezlerini engellemenin, iframe'de oturum açmış oturumu sürdürmeyi zorlaştırdığını unutmayın. Farklı tarayıcılarda çerez engellemenin geçerli durumu için https://www.cookiestatus.com adresine bakın. Elbette bu sorun Google Classroom eklentilerine özel değildir ve üçüncü tarafların iframe kullanan tüm web sitelerini etkiler. İş 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, üçüncü taraf bağlamındayken birinci taraf bağlamında oluşturulan çerezlere 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ı bekleniyor. İş ortaklarının gerektirdiği artışın nasıl azaltılacağı hakkında Google'a geri bildirim göndermek için özellik istekleri oluşturun.

URL normal ifadelerini kullanarak eklentilerin bulunabilirliğini etkinleştir

Öğretmenler sıklıkla bağlantı ekleri olan ödevler oluşturur. Eklentinizin kullanımını artırmak için eklentinizden erişilebilen kaynakların URL'leriyle eşleşen normal ifadeler belirtebilirsiniz. Normal ifadelerinizden biriyle eşleşen bir bağlantı ekleyen bir öğretmen, onu eklentinizi denemeye teşvik eden kapatılabilir bir iletişim kutusu görür. İletişim kutusunu yalnızca, eklentinin hesabında zaten yüklüyse görürler.

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

Şekil 1. Öğretmen, yeni bir ödevin bağlantısını seçerek ekleyebilirsiniz.

Şekil 2. Öğretmen üçüncü taraf bir kaynaktan bağlantı yapıştırır. Öğretmen, üçüncü tarafın Classroom eklentisini zaten yüklemişse.

Ş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.

Şekil 3'te gösterildiği gibi, pop penceredeki"Şimdi deneyin"i seçen öğretmenler, eklentinizin Ek Bulma iframe'ine yönlendirilir.