Bağlantı eklerini Classroom eklentisi eklerine yükseltin

Öğretmenlerin Classroom'a üçüncü taraf içeriği eklemek için kullandığı yöntemlerden biri, ödev oluşturma sayfasına bağlantı eki olarak bağlantı yapıştırmaktır. Öğretmenlerin zaten bildiği özelliklerden yararlanmak için eklentinizi, öğretmenlerin bir bağlantı ekini eklenti ekine yükseltmesine izin verecek şekilde yapılandırabilirsiniz.

Genel Bakış

Eklentinizi bu özelliği kullanarak yapılandırırsanız öğretmenler, ödev oluşturma sayfasına bir bağlantı eki yapıştırdıklarında bağlantıyı eklenti ekine yükseltmeleri istenir. Öğretmenlerden bu işlemi yapmaları yalnızca eklenti yüklüyse istenir.

Öğretmen, bağlantıyı eklenti ekine yükseltmeyi kabul ettiğinde, bağlantı yükseltme iFrame'i aşağıdaki sorgu parametreleriyle başlatılır:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (yalnızca kullanıcı uygulamanızı daha önce yetkilendirdiyse)

İlk dört sorgu parametresi, Ek Bulma iframe'inde başlatılan sorgu parametrelerini yansıtır. urlToUpgrade sorgu parametresi yenidir ve eklenti eklerinin nasıl oluşturulması gerektiğini değerlendirmenize yardımcı olabilir. Ardından, kullanıcının oturumunun açık olup olmadığını kontrol etmek için diğer sorgu parametrelerini kullanabilir ve itemType değerine bağlı olarak courseWork, courseWorkMaterials veya announcements yönteminin CreateAddOnAttachment yöntemini çağırabilirsiniz. Iframe içinde, eklenti eklerinin oluşturulduğunu öğretmene bildirmek için bir yükleme ekranı gösterebilirsiniz.

Eklenti eki oluşturulduktan sonra iFrame kapatılır ve öğretmen eki ödevde normal şekilde görüntüleyebilir.

Teknik uygulama ayrıntıları

Bu bölümde, özellikle ilgili bazı önemli teknik ayrıntılar vurgulanmaktadır.

urlToUpgrade sorgu parametresini okuma

urlToUpgrade sorgu parametresi, bağlantı yükseltme iframe'inde iletildiğinde URI olarak kodlanır. URL'yi orijinal biçiminde almak için kodunu çözmeniz gerekir. Örneğin, JavaScript kullanıyorsanız bunu yapmak için decodeURIComponent() işlevini kullanabilirsiniz.

Bu özellik için ideal bir kullanıcı deneyimi sağlamak amacıyla, eklenti eki başarıyla oluşturulduktan sonra bir postMessage gönderin. Bu işlem iframe'i kapatır. Daha fazla bilgi için iframe uygulama ayrıntıları sayfasına bakın.

Yapılandırma ayrıntıları

Bu özelliği eklentinize entegre etmek için aşağıdaki yapılandırmalar gerekir:

  • Bağlantı yükseltme iframe'inin URL'si: Öğretmen yükseltmeyi kabul ettiğinde iframe'de açılan URL'dir.

  • Classroom'un algılaması ve yükseltmeye çalışması gereken URL kalıpları: URL kalıpları, bir ana makine ve birden fazla yol ön ekinden oluşabilir.

    • Birden fazla URL kalıbı sağlayabilirsiniz.
    • Yol öneki sağlamazsanız ana makineyle eşleşen tüm URL'ler yükseltilebilir.
    • Yalnızca https şemasına sahip URL'ler yükseltilebilir.
    • URL kalıpları localhost içermemelidir.
    • Yol önekleri sorgu parametreleri veya URL parçaları içermemelidir.
    • Yol önekleri şu anda joker karakterleri destekleyebilir ancak ana makine adları destekleyemez:
      • example.com geçerli bir ana makine, /foo ve /bar/*/baz ise geçerli yol önekleridir.
      • example.*.host.com geçerli bir ana makine değil.
    • Yol öneki bileşenleri arasındaki bir joker karakter yalnızca tek bir bileşenle eşleşir ve eğik çizgilerle ayrılmış birden fazla bileşenle eşleşmez. Ana makinesi example.com ve yol öneki /bar/*/baz olan bir URL kalıbını ele alalım:
      • https://example.com/bar/123/baz, URL kalıbı için geçerli bir eşleşmedir.
      • https://example.com/bar/123/baz/456/789, URL kalıbı için geçerli bir eşleşmedir.
      • https://example.com/bar/123/456/baz, URL kalıbı için geçerli bir eşleşme değil çünkü yol önekindeki joker karakter /123/456/ ile eşleşmiyor.

Geliştirme süreci

Test veya üretim eklentiniz için bağlantı yükseltme iFrame URL'sini ve URL kalıplarını classroom-link-upgrade-external@google.com adresine e-posta göndererek iletin.

Classroom eklentisini temsil eden herhangi bir Google Cloud projesi için yapılandırmalar sağlayabilirsiniz. Öncelikle, canlı kullanıcıları etkilemeden bir demo alanında geliştirme ve test yapabilmeniz için eklentiye özel görünürlükle ilgili yapılandırmalar sağlamanızı öneririz.

Yapılandırmalar etkinleştirildiğinde e-postanıza yanıt alırsınız. localhost kullanan URL kalıplarının bu özellik için desteklenmediğini unutmayın.

E-postayı aşağıdaki bilgileri içerecek şekilde biçimlendirin:

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
-   Host:HOST_1
-   Path prefixes:
  -   PATH_PREFIX_1
  -   PATH_PREFIX_2

-   Host:HOST_2
-   Path prefixes:
  -   PATH_PREFIX_3
  -   PATH_PREFIX_4

// add more hosts and path prefixes as needed

Aşağıdakini değiştirin:

  • GCP_PROJECT_NUMBER: Eklentinin ilişkili olduğu Google Cloud projesinin numarası.
  • LINK_UPGRADE_IFRAME_URL: Bağlantı yükseltme iFrame'inde açılması gereken URL.
  • HOST_1: Classroom'un algılaması gereken bir sunucu. Yalnızca https şeması desteklenir.
  • PATH_PREFIX_1 ve PATH_PREFIX_2: Classroom'un algılaması ve yükseltmeye çalışması gereken HOST_1 ile ilişkili yol ön ekleri.
  • HOST_2: Classroom'un algılaması gereken bir sunucu. Yalnızca https şeması desteklenir.
  • PATH_PREFIX_3 ve PATH_PREFIX_4: Classroom'un algılaması ve yükseltmeye çalışması gereken HOST_2 ile ilişkili yol ön ekleri.

Bu özelliği uygularken dikkate almanız gereken öneriler aşağıda verilmiştir.

Öğretmenlerin fazladan çalışmasını önleme

Gerekirse oturum açmayı kolaylaştırmak veya bir yükleme göstergesi görüntülemek için iFrame'i kullanmanızı önemle tavsiye ederiz. En iyi kullanıcı deneyimi için, yapıştırılan bağlantının eklenti ekine yükseltilmesini kabul eden öğretmenden başka bilgi istenmemelidir. Ancak bu, eklentiniz için mümkün değilse ihtiyacınız olan ek bilgileri toplamak için Link Upgrade iFrame'ini kullanabilirsiniz. Bağlantının yükseltilmesi mümkün değilse veya bir hata oluştuysa iFrame, öğretmeni bilgilendirmek için de kullanılabilir.

Kullanıcı dostu erişim hata mesajları ekleyin

Öğretmenler, erişimlerinin olmadığı bir bağlantıyı yapıştırıp yükseltirse sorundan haberdar olmaları için iFrame'de kullanıcı dostu bir hata mesajı gösterilir. Iframe, öğretmene içeriğe erişmek için uygun izinleri vermek amacıyla da kullanılabilir.