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. Sie können Ihr Add-on jetzt so konfigurieren, dass Lehrkräfte einen Link-Anhang in einen Add-on-Anhang umwandeln können.

Übersicht

Wenn Sie Ihr Add-on mit dieser Funktion konfigurieren, werden Lehrkräfte aufgefordert, einen Link in einen Add-on-Anhang umzuwandeln, wenn sie einen Link-Anhang auf der Seite zum Erstellen von Aufgaben 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 Suchparameter spiegeln die Suchparameter wider, die im iframe für die Suche nach Anhängen verwendet werden. Der Abfrageparameter urlToUpgrade ist neu und kann Ihnen dabei helfen, zu beurteilen, wie der Add-on-Anhang erstellt werden sollte. Anschließend kannst du mit den anderen Abfrageparametern prüfen, ob der Nutzer angemeldet ist, und die Methode CreateAddOnAttachment von courseWork, courseWorkMaterials oder announcements basierend auf dem Wert von 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 in der Aufgabe wie gewohnt aufrufen.

Technische Implementierungsdetails

In diesem Abschnitt werden einige wichtige technische Details zur Funktion beschrieben.

urlToUpgrade-Abfrageparameter lesen

Der Abfrageparameter urlToUpgrade wird URI-codiert, wenn er über den Link-Upgrade-Iframe übergeben wird. Sie müssen die URL decodieren, um sie in ihrer ursprünglichen Form zu erhalten. Wenn Sie beispielsweise JavaScript verwenden, können Sie dazu die Funktion decodeURIComponent() verwenden.

iFrame für die Link-Aufrüstung schließen

Damit die Nutzer diese Funktion optimal nutzen können, senden Sie eine postMessage, sobald der Add-on-Anhang erfolgreich erstellt wurde. Dadurch wird der iFrame geschlossen. Weitere Informationen finden Sie auf der Seite mit Details zur iFrame-Implementierung.

Konfigurationsdetails

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

• URL für den iFrame für die Link-Upgrade-Funktion: Diese URL wird im iFrame geöffnet, wenn ein*e Lehrkraft dem Upgrade zustimmt.

• URL-Muster, die Classroom erkennen und versuchen sollte, zu aktualisieren: 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 einem https-Schema können umgestellt werden.
  • URL-Muster dürfen localhost nicht enthalten.
  • Pfadpräfixe dürfen keine Suchparameter oder URL-Fragmente enthalten.
  • Pfadpräfixe können derzeit Platzhalter unterstützen, Hosts jedoch nicht:
    • 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 den Pfadpräfixkomponenten entspricht nur einer einzelnen Komponente und nicht mehreren Komponenten, die durch Schrägstriche getrennt sind. Angenommen, Sie haben ein URL-Muster mit dem Host example.com und dem Pfadpräfix /bar/*/baz:
    • https://example.com/bar/123/baz ist eine gültige Übereinstimmung für das URL-Muster.
    • https://example.com/bar/123/baz/456/789 ist eine gültige Übereinstimmung für das 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.

Hinweis: Platzhalter zwischen Pfadpräfix-Komponenten stimmen nur mit einer einzelnen Komponente überein.

Entwicklungsablauf

Senden Sie die iFrame-URL und die URL-Muster für die Link-Upgrade-Funktion für Ihr Test- oder Produktions-Add-on per E-Mail an [e-mail].

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 es in einer Demodomain entwickeln und testen können, ohne dass es sich auf Livenutzer auswirkt.

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

Wichtig :Nutzer, die Ihr Add-on installieren und verwenden können, können Links zu Add-on-Anhängen upgraden, sobald die Konfigurationen vom Classroom-Team aktiviert wurden. Daher ist es wichtig, zuerst Konfigurationen für Ihr Test-Add-on in einer Test- oder Entwicklungsumgebung bereitzustellen, bevor Sie Produktionskonfigurationen bereitstellen.

Formatieren Sie die E-Mail so, dass sie Folgendes enthält:

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 für das Link-Upgrade geöffnet werden soll.
• HOST_1: Ein Host, der von Classroom erkannt werden soll. Nur das https-Schema wird unterstützt.
• PATH_PREFIX_1 und PATH_PREFIX_2: Pfadpräfixe, die mit HOST_1 verknüpft sind und in Classroom erkannt und aktualisiert werden sollen.
• HOST_2: Ein Host, der von Classroom erkannt werden soll. Nur das https-Schema 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.

Empfohlene Nutzererfahrung

Im Folgenden finden Sie einige Vorschläge für die Implementierung dieser Funktion.

Mehr Zeit für Lehrkräfte

Wir empfehlen dringend, den iFrame zu verwenden, um die Anmeldung zu vereinfachen, falls erforderlich, oder einen Ladebalken 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 jedoch nicht möglich ist, können Sie mit dem iframe für das Link-Upgrade zusätzliche Informationen erfassen, die Sie benötigen. Über den Iframe kann die Lehrkraft auch darüber informiert werden, wenn das Upgrade des Links 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 im Iframe eine nutzerfreundliche Fehlermeldung angezeigt, damit Lehrkräfte auf das Problem aufmerksam werden. Über den Iframe können Sie der Lehrkraft auch die entsprechenden Berechtigungen für den Zugriff auf die Inhalte erteilen.