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, einen Link als Link-Anhang auf der Seite zum Erstellen von Aufgaben 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 zugestimmt hat, den Link in einen Add-on-Anhang umzuwandeln, wird der Iframe „Link-Upgrade“ mit den folgenden Abfrageparametern gestartet:

• courseId
• itemId
• itemType
• addOnToken
• urlToUpgrade
• login_hint (nur, wenn der Nutzer Ihre 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 entscheiden, wie der Add-on-Anhang erstellt werden soll. 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. Im Iframe können Sie einen Ladebildschirm anzeigen, 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 sich den Anhang in der Aufgabe wie gewohnt ansehen.

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 iframe für die Link-Upgrade-Funktion ü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

Für die Einbindung dieser Funktion in Ihr Add-on sind die folgenden Konfigurationen erforderlich:

• URL für den iFrame zum Link-Upgrade: 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 jede URL, die mit dem Host übereinstimmt, umgestellt 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 durch Schrägstriche getrennten Komponenten. 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 für das URL-Muster, da der Platzhalter im Pfadpräfix nicht mit /123/456/ übereinstimmt.

Hinweis: Platzhalter zwischen Pfadpräfixkomponenten stimmen nur mit einer einzelnen Komponente überein.

Entwicklungsablauf

Senden Sie die iFrame-URL und die URL-Muster für das Link-Upgrade 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: Pfadpräfixe, die mit HOST_2 verknüpft sind und in Classroom erkannt und aktualisiert werden sollen.

Empfohlene Nutzererfahrung

Nachfolgend 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 der*die Lehrkraft nach der Zustimmung zur Umwandlung des eingefügten Links in einen Add-on-Anhang nicht noch einmal um zusätzliche Informationen gebeten werden. 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 zum Zugriff einbinden

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.