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 doğrulamak 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:

• HTTPS gereklidir. TLS 1.2 veya daha yeni bir sürümün kullanılmasını ve HTTP Katı Taşıma Güvenliği'nin (HSTS) etkinleştirilmesini önemle tavsiye ederiz. Katı Taşıma Güvenliği hakkında ilgili MDN makalesine bakın.
• Katı İçerik Güvenliği Politikası'nı (Strict CSP) 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 bu konuyla ilgili Çerezler MDN makalesine bakın.

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 hakkında bilgi sağlar.

Kurs kimliği

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

Tüm iframe'lerde bulunur.

Öğe Kimliği

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

Tüm iframe'lerde bulunur.

Öğ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'lerde bulunur.

Ek Kimliği

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

teacherViewUri, studentViewUri ve studentWorkReviewUri iframe'leriyle birlikte sunulur.

Gönderim kimliği

submissionId değeri, öğrencinin çalışması için bir tanımlayıcıdır ancak belirli bir ödevdeki öğ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 ödevde 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.

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. 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. Kullanıcının oturum açma iletişim kutusu göründüğünde kimlik bilgilerini girmesi gerekmemesi 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ış 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'lerde bulunur.

Ek Bulma iframe'i

Örnek ek keşfi 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

studentWorkReviewUri iframe

Bağlantı yükseltme iframe'i

Örnek bağlantı yükseltme senaryosu

1. Bir Classroom eklentisi, https://example.com/upgrade Link Upgrade URI'siyle kaydedilmiştir. Classroom'un bağlantı eklerini eklenti ekine yükseltmeyi denemesi 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.
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ı ekle 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 ç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 birlikte {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 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 çerezlerini engelleme

Üçüncü taraf çerezlerinin engellenmesinin, bir iFrame'de oturum açılmış bir oturumu sürdürmeyi 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 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, üçü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 özellik, tüm kullanıcılar için her zaman kullanılamayabilir.
• Ç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.

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

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

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