Google Classroom-Add-ons sind jetzt allgemein für Entwickler verfügbar. Weitere Informationen finden Sie in der Dokumentation zu Add-ons.

Diese Seite wurde von der Cloud Translation API übersetzt.

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

Lehrkräfte können Drittanbieterinhalte in Classroom einfügen, indem sie auf der Seite zum Erstellen von Aufgaben einen Link als Linkanhang einfügen. Um an das anzuknüpfen, was Lehrkräfte bereits kennen, können Sie Ihr Add-on jetzt so konfigurieren, dass Lehrkräfte einen Linkanhang in einen Add-on-Anhang umwandeln können.

Übersicht

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

Sobald die Lehrkraft dem Upgrade des Links zu einem Add-on-Anhang zustimmt, wird das Link-Upgrade-iFrame mit den folgenden Suchparametern gestartet:

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

Die ersten vier Suchparameter entsprechen den Suchparametern, die im Attachment Discovery-iFrame gestartet wurden. Der neue Abfrageparameter urlToUpgrade kann Ihnen dabei helfen, zu beurteilen, wie die Add-on-Anlage erstellt werden soll. 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 von itemType aufrufen. Im iFrame können Sie einen Ladebildschirm anzeigen, um der Lehrkraft mitzuteilen, dass der Add-on-Anhang erstellt wird.

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

Technische Details zur Implementierung

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

`urlToUpgrade`-Abfrageparameter lesen

Der Abfrageparameter urlToUpgrade wird URI-codiert, wenn er an das 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 zum Link-Upgrade schließen

Damit die Nutzererfahrung mit dieser Funktion optimal ist, senden Sie ein postMessage, sobald der Add-on-Anhang erfolgreich erstellt wurde. Dadurch wird der iFrame geschlossen. Weitere Informationen finden Sie auf der Seite Details zur iFrame-Implementierung.

Konfigurationsdetails

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

URL für den iFrame zur Link-Umstellung: Dies ist die URL, die im iFrame geöffnet wird, wenn ein Lehrer 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 jede URL, die mit dem Host übereinstimmt, auf HTTPS umgestellt werden.
- Nur URLs mit dem Schema https können aktualisiert werden.
- URL-Muster dürfen nicht localhost 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 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.

Entwicklungsablauf

Senden Sie die iFrame-URL für das Link-Upgrade und die URL-Muster 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 bereitstellen, das ein Classroom-Add-on darstellt. Wir empfehlen, zuerst Konfigurationen für ein Add-on mit privater Sichtbarkeit bereitzustellen, damit Sie in einer Demodomäne entwickeln und testen können, ohne dass sich dies auf aktive Nutzer auswirkt.

Sie erhalten eine Antwort auf Ihre E‑Mail, sobald die Konfigurationen aktiviert wurden. URL-Muster, in denen localhost verwendet wird, 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, dem das Add-on zugeordnet 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 die Classroom erkennen und versuchen sollte, zu aktualisieren.
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 die Classroom erkennen und versuchen sollte, zu aktualisieren.

Empfohlene Nutzererfahrung

Hier sind einige Vorschläge, die Sie bei der Implementierung dieses Features berücksichtigen sollten.

Zusätzliche Arbeit für Lehrkräfte vermeiden

Wir empfehlen dringend, das iFrame zu verwenden, um die Anmeldung zu erleichtern, falls erforderlich, oder einen Ladeindikator anzuzeigen. Für eine optimale Nutzerfreundlichkeit sollte der Lehrer nicht nach zusätzlichen Informationen gefragt werden, nachdem er zugestimmt hat, den eingefügten Link in einen Add-on-Anhang umzuwandeln. Wenn dies für Ihr Add-on nicht möglich ist, können Sie das Link Upgrade-Iframe verwenden, um zusätzliche Informationen zu erfassen, die Sie benötigen. Das iFrame kann auch verwendet werden, um den Lehrkraft zu informieren, wenn ein Upgrade des Links nicht möglich ist oder ein Fehler aufgetreten ist.

Nutzerfreundliche Fehlermeldungen für den Zugriff einbinden

Wenn Lehrkräfte einen Link einfügen und aktualisieren, auf den sie keinen Zugriff haben, sollte im iFrame eine nutzerfreundliche Fehlermeldung angezeigt werden, damit sie über das Problem informiert sind. Das iFrame kann auch verwendet werden, um der Lehrkraft die entsprechenden Berechtigungen für den Zugriff auf die Inhalte zu gewähren.