iFrame ve sorgu parametresi ayrıntıları

Classroom eklentileri, son kullanıcıya sorunsuz ve rahat bir kullanıcı deneyimi sunmak için bir iFrame'de yüklenir. Beş farklı iFrame türü vardır. Her iFrame'in amacı ve görünümüyle ilgili genel bir bakış için Kullanıcı yolculukları dizinindeki iFrame sayfalarına bakın.

iframe güvenlik yönergeleri

Geliştiricilerin, iFrame'lerini güvence altına almak için sektördeki en iyi uygulamaları takip etmesi beklenir. Ancak, geçerli kimlik bilgilerine sahip olduğunuzu ve kullanıcının kurstaki rolünü doğru şekilde tanımlayabildiğinizi onaylamak için kullanıcı akışınıza belirli API etkileşimlerini de dahil etmeniz gerekir.

Sunucu uygulaması yapılandırması

iFrame'i korumak için aşağıdaki sunucu yapılandırmalarını öneririz:

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, eklentiye ders, ödev, eklenti eki, öğrencinin gönderimi ve yetkilendirme jetonu hakkında bilgi sağlar.

Kurs kimliği

courseId değeri, kursun tanımlayıcısıdır.

Tüm iFrame'lere dahildir.

Öğe Kimliği

itemId değeri, bu eklerin iliştirildiği Announcement, CourseWork veya CourseWorkMaterial öğesinin tanımlayıcısıdır.

Tüm iFrame'lere dahildir.

Öğe Türü

itemType değeri, bu eklerin iliştirildiği kaynak türünü tanımlar. Geçirilen dize değeri "announcements", "courseWork" veya "courseWorkMaterials" olmalıdır.

Tüm iFrame'lere dahildir.

Ek Kimliği

attachmentId değeri, ekin tanımlayıcısıdır.

teacherViewUri, studentViewUri ve studentWorkReviewUri iframe'leri ile birlikte sunulur.

Gönderim kimliği

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

studentWorkReviewUri ile birlikte sunulur.

Eklenti jetonu

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

Ek Bulma iFrame'i ve Bağlantı Yükseltme iFrame'i ile birlikte kullanılır.

Yeni sürüme geçirilecek URL

urlToUpgrade değerinin bulunması, öğretmenin ödeve bağlantı eki eklediği ve bunu ek eki olarak yükseltmeyi kabul ettiği anlamına gelir. Bu özelliği henüz yapılandırmadıysanız daha fazla bilgi için ek eklentileri eklemek üzere bağlantıları yükseltme hakkındaki kılavuza bakın.

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

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. Kullanıcı, son kullanıcı oturum açma sürecindeki zorlukları azaltmak için 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ı'nın benzersiz tanımlayıcısıdır. Kullanıcı eklentinize ilk kez giriş yaptıktan sonra, aynı kullanıcının eklentinizi sonraki her ziyaretinde login_hint parametresi iletilir.

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

  1. Kimlik doğrulama akışı sırasında login_hint değerini iletin. Böylece, oturum açma iletişim kutusu göründüğünde kullanıcının kimlik bilgilerini girmesi gerekmez. Kullanıcının oturumu otomatik olarak açılmaz.
  2. Kullanıcı oturum açtıktan sonra, değeri eklentide oturum açmış olabilecek diğer kullanıcılarla karşılaştırmak için bu parametreyi kullanın. Eşleşme bulursanız kullanıcının oturumunu açık bırakabilir ve oturum açma akışı göstermeden devam edebilirsiniz. Parametre, oturum açmış kullanıcılarınızdan herhangi biriyle eşleşmiyorsa kullanıcıdan Google markalı bir oturum açma düğmesiyle oturum açmasını isteyin.

Tüm iFrame'lere dahildir.

Ek Bulma iframe'i

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

Örnek ek keşfetme senaryosu

  1. Classroom eklentisi, Google Workspace Marketplace'e https://example.com/addon ek bulma URI'siyle kaydedilir.
  2. Bir öğretmen bu eklentiyi yükleyip kurslarından birinde yeni bir duyuru, ödev veya materyal oluşturduğunda Ö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. Eklenti, ek seçimi yapıldığında iframe'i kapatmak için Classroom'a postMessage gönderir.

teacherViewUri ve studentViewUri iframe'leri

Boyut Açıklama
Zorunlu Evet
URI teacherViewUri veya studentViewUri
Sorgu Parametreleri courseId, itemId, itemType, attachmentId ve login_hint.
Yükseklik Pencere yüksekliğinin% 100'ü eksi üst başlık için 140 piksel
Genişlik %100 pencere genişliği

studentWorkReviewUri iframe'i

Boyut Açıklama
Zorunlu Hayır (Bunun bir etkinlik türü eki olup olmadığını belirler)
URI studentWorkReviewUri
Sorgu Parametreleri courseId, itemId, itemType, attachmentId, submissionId ve login_hint.
Yükseklik Üst başlıktaki 168 piksel hariç% 100 pencere yüksekliği
Genişlik Pencere genişliğinin% 100'ü eksi kenar çubuğu genişliği<> Kenar çubuğu genişletildiğinde 312 piksel, daraltıldığında ise 56 pikseldir.
Boyut Açıklama
Zorunlu Evet, bağlantıları eklenti eklerine yükseltme eklentiniz tarafından destekleniyorsa.
URI Eklenti meta verilerinde sağlanır.
Sorgu Parametreleri courseId, itemId, itemType, addOnToken, urlToUpgrade ve login_hint.
Yükseklik Pencere yüksekliğinin% 80'i eksi üst başlık için 60 piksel
Genişlik Maksimum 1.600 piksel
Pencere genişliği <= 600 piksel olduğunda pencere genişliğinin% 90'ı
Pencere genişliği > 600 piksel olduğunda pencere genişliğinin% 80'i
  1. Bir Classroom eklentisi, https://example.com/upgrade Link Upgrade URI'siyle kaydedilmiştir. Classroom'un bağlantı eklerini eklenti ekine yükseltmeye çalışması için aşağıdaki barındırıcı ve yol öneki kalıplarını sağladınız:
    • Ana makine example.com, yol öneki ise /quiz.
  2. Bir öğretmen, kurslarından birinde yeni bir duyuru, ödev veya materyal oluşturduğunda Örneğin, itemId=234, itemType=courseWork ve courseId=123.
  3. Bir öğretmen, sağladığınız URL kalıbıyla eşleşen bir bağlantıyı (https://example.com/quiz/5678) Bağlantı ekleme iletişim kutusuna yapıştırır. Öğretmenden daha sonra bağlantıyı eklenti ekine yükseltmesi istenir.

  4. Classroom, URL'si https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 olarak ayarlanmış 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'e iletilirken URI olarak kodlandığını unutmayın. Parametreyi orijinal biçiminde elde etmek için kodunu çözmeniz gerekir. Örneğin, JavaScript decodeURIComponent() işlevini sunar.

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

iFrame'i kapatın.

Iframe, postMessage yüküyle {type: 'Classroom', action: 'closeIframe'} gönderilerek öğrenme aracından kapatılabilir. Classroom yalnızca açılan orijinal URI'ye karşılık gelen host_name+port'tan gelen bu postMessage öğesini 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ı ve bağlantı noktası, iFrame'i başlatmak için kullanılan URI'nin alan adı ve bağlantı noktasıyla aynı olmalıdır. Aksi takdirde mesaj yoksayılır. Geçici çözüm olarak, orijinal alandaki bir sayfaya geri yönlendirme yapabilirsiniz. Bu sayfa, postMessage etkinliğini göndermekten başka bir işlem yapmaz.

Yeni sekmeden iFrame'i kapatma

Web alanları arası korumalar bunun çalışmasını engeller. Bu sorunu çözmek için iframe ile yeni sekme arasındaki iletişimi kendiniz yönetebilir ve kapatma postMessage etkinliğini yayınlamaktan nihayetinde iframe'in sorumlu olmasını sağlayabilirsiniz. Ek olarak, 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 sandbox özellikleri ile 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 çerezlerinin engellenmesinin, bir iFrame'de imzalı bir oturumun sürdürülmesini zorlaştırdığını unutmayın. Farklı tarayıcılarda çerez engellemenin mevcut durumu hakkında bilgi edinmek için https://www.cookiestatus.com adresini ziyaret edin. Elbette bu sorun yalnızca Google Classroom eklentilerine özgü değildir ve üçüncü tarafları iFrame'e yerleştiren tüm web sitelerini etkiler. İş ortaklarımızın çoğu bu sorunla karşılaşmıştır.

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

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

Gelecekteki tarayıcı sürümlerinde daha fazla çerez kısıtlaması beklenmektedir. İş ortaklarının ihtiyaç duyduğu artışı azaltma konusunda Google'a geri bildirim göndermek için özellik istekleri oluşturun.

URL normal ifadelerini kullanarak eklentilerin bulunabilirliğini etkinleştirme

Öğretmenler genellikle 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 öğretmen, eklentinizi denemeye teşvik eden ve kapatılabilir bir iletişim kutusu görür. Kullanıcılar, iletişim kutusunu yalnızca eklenti hesaplarına zaten yüklenmişse görür.

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

Öğretmen, bağlantı ekini seçiyor Şekil 1. Öğretmen, yeni bir ödeve bağlantı ekliyor.

Öğretmen bağlantı yapıştırıyor Şekil 2. Öğretmen, üçüncü taraf bir kaynaktan bağlantı yapıştırıyor. Öğretmen, üçüncü tarafın Classroom eklentisini daha önce yüklemiş olmalıdır.

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

Bir öğretmen, Şekil 3'te gösterilen pop-up'ta "Şimdi dene"yi seçerse eklentinizin Ek Bulma iFrame'ine yönlendirilir.