Linkanhänge auf Classroom-Add-on-Anhänge aktualisieren

Eine Möglichkeit, wie Lehrkräfte Inhalte von Drittanbietern in Classroom hinzufügen können, besteht darin, auf der Seite zur Aufgabenerstellung einen Link als Linkanhang einzufügen. Nun können Sie Ihr Add-on so konfigurieren, dass Lehrkräfte einen Linkanhang auf einen Add-on-Anhang umstellen können.

Überblick

Wenn Sie Ihr Add-on mit dieser Funktion konfigurieren, werden Lehrkräfte aufgefordert, einen Link zu einem Add-on-Anhang zu aktualisieren, wenn sie einen Linkanhang auf der Seite zur Aufgabenerstellung einfügen. Lehrkräfte werden nur dazu aufgefordert, wenn sie das Add-on bereits installiert haben.

Sobald die Lehrkraft dem Upgrade des Links auf einen Add-on-Anhang zustimmt, wird der iFrame des Linkupgrades mit den folgenden Abfrageparametern gestartet:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (nur, wenn der Nutzer deine App bereits autorisiert hat)

Die ersten vier Abfrageparameter spiegeln die Suchparameter wider, die im iFrame der Anhangserkennung gestartet wurden. Der Abfrageparameter urlToUpgrade ist neu und kann Ihnen dabei helfen, zu beurteilen, wie der Add-on-Anhang erstellt werden sollte. Anschließend können Sie mit den anderen Abfrageparametern prüfen, ob der Nutzer angemeldet ist, und die Methode CreateAddOnAttachment von courseWork, courseWorkMaterials oder announcements basierend auf dem Wert itemType aufrufen. Innerhalb des iFrames können Sie einen Ladebildschirm anzeigen lassen, um die Lehrkraft darüber zu informieren, dass der Add-on-Anhang erstellt wird.

Sobald der Add-on-Anhang erstellt wurde, wird der iFrame geschlossen und die Lehrkraft kann den Anhang wie gewohnt in der Aufgabe ansehen.

Details zur technischen Implementierung

In diesem Abschnitt werden einige wichtige technische Details zu dieser Funktion erläutert.

Abfrageparameter urlToUpgrade lesen

Der Abfrageparameter urlToUpgrade wird URI-codiert, wenn er an den iFrame des Linkupgrades übergeben wird. Sie müssen die URL decodieren, um sie in ihrer ursprünglichen Form abzurufen. Wenn Sie beispielsweise JavaScript verwenden, können Sie dazu die Funktion decodeURIComponent() verwenden.

Damit dieses Feature optimal genutzt werden kann, senden Sie eine postMessage, nachdem der Add-on-Anhang erfolgreich erstellt wurde. Dadurch wird der iFrame geschlossen. Weitere Informationen finden Sie auf der Detailseite zur iFrame-Implementierung.

Konfigurationsdetails

Die folgenden Konfigurationen sind erforderlich, um dieses Feature in Ihr Add-on zu integrieren:

  • URL für den iFrame des Linkupgrades: Dies ist die URL, die im iFrame geöffnet wird, wenn die Lehrkraft der Umstellung zustimmt.

  • URL-Muster, die von Classroom erkannt und aktualisiert werden sollen: Die URL-Muster können aus einem Host und mehreren Pfadpräfixen bestehen.

    • Sie können mehrere URL-Muster angeben.
    • Wenn Sie keine Pfadpräfixe angeben, kann für jede URL, die mit dem Host übereinstimmt, ein Upgrade durchgeführt werden.
    • Nur URLs mit dem Schema https können umgestellt werden.
    • URL-Muster dürfen nicht localhost enthalten.
    • Pfadpräfixe dürfen keine Suchparameter oder URL-Fragmente enthalten.
    • Für Pfadpräfixe können derzeit Platzhalter verwendet werden. Für Hosts ist Folgendes nicht möglich:
      • example.com ist ein gültiger Host und /foo und /bar/*/baz sind gültige Pfadpräfixe.
      • example.*.host.com ist kein gültiger Host.
    • Ein Platzhalter zwischen Pfadpräfixkomponenten entspricht nur einer einzelnen Komponente und nicht mehrerer Komponenten, die durch Schrägstriche getrennt sind. Sehen Sie sich ein URL-Muster mit dem Host example.com und dem Pfadpräfix /bar/*/baz an:
      • https://example.com/bar/123/baz ist eine gültige Übereinstimmung mit dem URL-Muster.
      • https://example.com/bar/123/baz/456/789 ist eine gültige Übereinstimmung mit dem URL-Muster.
      • https://example.com/bar/123/456/baz ist keine gültige Übereinstimmung mit dem URL-Muster, da der Platzhalter im Pfadpräfix nicht mit /123/456/ übereinstimmt.

Entwicklungsablauf

Senden Sie die iFrame-URL und URL-Muster des Linkupgrades für Ihr Test- oder Produktions-Add-on per E-Mail an classroom-link-upgrade-external@google.com.

Sie können Konfigurationen für jedes Google Cloud-Projekt angeben, das ein Classroom-Add-on darstellt. Wir empfehlen, zuerst Konfigurationen für ein Add-on mit privater Sichtbarkeit bereitzustellen, damit Sie in einer Demodomain entwickeln und testen können, ohne Livenutzer zu beeinträchtigen.

Sie erhalten eine Antwort auf Ihre E-Mail, wenn die Konfigurationen aktiviert wurden. URL-Muster, die localhost verwenden, werden für diese Funktion nicht unterstützt.

Die E-Mail sollte Folgendes enthalten:

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

Ersetzen Sie Folgendes:

  • GCP_PROJECT_NUMBER: Die Nummer des Google Cloud-Projekts, mit dem das Add-on verknüpft ist.
  • LINK_UPGRADE_IFRAME_URL: Die URL, die im iFrame vom Typ „Linkupgrade“ geöffnet werden soll.
  • HOST_1: Ein Host, den Classroom erkennen soll. Nur das Schema https wird unterstützt.
  • PATH_PREFIX_1 und PATH_PREFIX_2: mit HOST_1 verknüpfte Pfadpräfixe, die von Classroom erkannt und aktualisiert werden sollen.
  • HOST_2: Ein Host, den Classroom erkennen soll. Nur das Schema https wird unterstützt.
  • PATH_PREFIX_3 und PATH_PREFIX_4: mit HOST_2 verknüpfte Pfadpräfixe, die von Classroom erkannt und aktualisiert werden sollen.

Im Folgenden finden Sie einige Vorschläge, die Sie bei der Implementierung dieser Funktion berücksichtigen sollten.

Mehraufwand für Lehrkräfte

Wir empfehlen dringend, den iFrame zu verwenden, um die Anmeldung zu erleichtern oder eine Ladeanzeige anzuzeigen. Aus Gründen der Nutzerfreundlichkeit sollte die Lehrkraft nicht nach zusätzlichen Informationen gefragt werden, nachdem sie zugestimmt hat, den eingefügten Link in einen Add-on-Anhang zu aktualisieren. Wenn dies für Ihr Add-on nicht möglich ist, können Sie den iFrame des Linkupgrades verwenden, um zusätzliche Informationen zu erfassen, die Sie benötigen. Über den iFrame kann die Lehrkraft außerdem informiert werden, wenn ein Upgrade der Verknüpfung nicht möglich ist oder ein Fehler aufgetreten ist.

Nutzerfreundliche Fehlermeldungen beim Zugriff anzeigen

Wenn Lehrkräfte einen Link einfügen und aktualisieren, auf den sie keinen Zugriff haben, wird eine nutzerfreundliche Fehlermeldung im iFrame angezeigt, damit Lehrkräfte über das Problem informiert sind. Über den iFrame können auch die entsprechenden Berechtigungen für den Zugriff auf die Inhalte der Lehrkraft erteilt werden.