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

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

Lehrkräfte können in Classroom Inhalte von Dritten hinzufügen, indem sie auf der Seite zum Erstellen von Aufgaben einen Link als Linkanhang einfügen. Um Lehrkräften die Verwendung der Funktion zu erleichtern, können Sie Ihr Add-on so konfigurieren, dass sie 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 in einen Add-on-Anhang umzuwandeln, wenn sie auf der Seite zum Erstellen von Aufgaben einen Linkanhang einfügen. Lehrkräfte werden nur dann dazu aufgefordert, wenn sie das Add-on bereits installiert haben.

Sobald die Lehrkraft zustimmt, den Link in einen Add-on-Anhang umzuwandeln, wird der iFrame „Link-Upgrade“ 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 iFrame „Anhangsuche“ gestartet werden. Der Suchparameter urlToUpgrade ist neu und kann Ihnen helfen, zu beurteilen, wie der Add-on-Anhang erstellt werden soll. Anschließend können Sie mit den anderen Suchparametern prüfen, ob der Nutzer angemeldet ist, und die CreateAddOnAttachment Methode 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 der iFrame geschlossen und die Lehrkraft kann den Anhang in der Aufgabe wie gewohnt sehen.

Technische Implementierungsdetails

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

Suchparameter `urlToUpgrade` lesen

Der Suchparameter urlToUpgrade ist URI-codiert, wenn er an den iFrame „Link-Upgrade“ ü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 „Link-Upgrade“ schließen

Um eine optimale Nutzererfahrung für diese Funktion zu gewährleisten, senden Sie eine postMessage, sobald 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 diese Funktion in Ihr Add-on zu integrieren:

URL für den iFrame „Link-Upgrade“: Dies ist die URL, die im iFrame geöffnet wird, wenn eine Lehrkraft zustimmt, ein Upgrade durchzuführen.
URL-Muster, die in Classroom erkannt und für die ein Upgrade versucht werden soll: Die URL-Muster können aus einem Host und mehreren Pfad präfixen bestehen.
- Sie können mehrere URL-Muster angeben.
- Wenn Sie keine Pfadpräfixe angeben, kann jede URL, die mit dem Host übereinstimmt, aktualisiert werden.
- Es können nur URLs mit dem Schema https 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 stimmt nur mit einer einzelnen Komponente überein und nicht mit mehreren Komponenten, die durch Schrägstriche getrennt sind. Betrachten Sie 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 URL des iFrames „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 angeben, das ein Classroom-Add-on darstellt. Wir empfehlen, zuerst Konfigurationen für ein Add-on mit privater Sichtbarkeit anzugeben, damit Sie in einer Demodomain entwickeln und testen können, ohne dass sich dies auf aktive Nutzer auswirkt.

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.

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 „Link-Upgrade“ geöffnet werden soll.
HOST_1: Ein Host, der in Classroom erkannt werden soll. Nur das https-Schema wird unterstützt.
PATH_PREFIX_1 und PATH_PREFIX_2: Pfad präfixe, die mit HOST_1 verknüpft sind und die in Classroom erkannt und für die ein Upgrade versucht werden soll.
HOST_2: Ein Host, der in Classroom erkannt werden soll. Nur das https-Schema wird unterstützt.
PATH_PREFIX_3 und PATH_PREFIX_4: Pfad präfixe, die mit HOST_2 verknüpft sind und die in Classroom erkannt und für die ein Upgrade versucht werden soll.

Empfohlene Nutzererfahrung

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

Zusätzliche Arbeit für Lehrkräfte vermeiden

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

Nutzerfreundliche Fehlermeldungen für Zugriffsfehler einfügen

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