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

Eine Möglichkeit, wie Lehrkräfte Inhalte von Drittanbietern zu Classroom hinzufügen können, besteht darin, auf der Seite zum Erstellen von Aufgaben einen Link als Linkanhang einzufügen. Um auf dem aufzubauen, mit dem Lehrkräfte bereits vertraut sind, können Sie Ihr Add-on jetzt 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 zum Erstellen von Aufgaben einfügen. Lehrkräfte werden nur dann dazu aufgefordert, wenn sie das Add-on bereits installiert haben.

Sobald die Lehrkraft dem Upgrade des Links auf einen Add-on-Anhang zugestimmt hat, wird der iFrame für die Linkaktualisierung mit den folgenden Abfrageparametern gestartet:

• courseId
• itemId (umbenannt von postId)
• itemType (neu!)
• addOnToken
• login_hint oder hd
• urlToUpgrade (neu!)

Die ersten vier Abfrageparameter entsprechen den Abfrageparametern, die im iFrame der Anhangerkennung gestartet wurden. Der Abfrageparameter urlToUpgrade ist neu und hilft Ihnen bei der Beurteilung, wie der Add-on-Anhang 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 itemType aufrufen. Innerhalb des iFrames können Sie einen Ladebildschirm einblenden, um die Lehrkraft darüber zu informieren, dass der Add-on-Anhang erstellt wird.

Nachdem 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 für die Funktion beschrieben.

urlToUpgrade-Abfrageparameter 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 zu erhalten. Wenn du beispielsweise JavaScript verwendest, kannst du dazu die Funktion decodeURIComponent() verwenden.

iFrame für Link-Upgrade schließen

Senden Sie eine postMessage, nachdem der Add-on-Anhang erfolgreich erstellt wurde, um dieses Feature optimal zu nutzen. Dadurch wird der iFrame geschlossen. Weitere Informationen finden Sie auf der Seite mit den Details zur iFrame-Implementierung.

Konfigurationsdetails

Die folgenden Konfigurationen sind erforderlich, um diese Funktion in Ihr Add-on zu integrieren:

• URL für den iFrame für die Linkaktualisierung: Das ist die URL, die im iFrame geöffnet wird, wenn die Lehrkraft dem Upgrade zustimmt.

• URL-Muster, die Classroom erkennen und aktualisieren sollte: 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, aktualisiert 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.
  • Pfadpräfixe unterstützen derzeit Platzhalter, 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. 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 für das URL-Muster, da der Platzhalter im Pfadpräfix nicht mit /123/456/ übereinstimmt.

Hinweis :Platzhalter zwischen Pfadpräfixkomponenten entsprechen nur einer einzelnen Komponente.

Entwicklungsablauf

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

Sie können zuerst Konfigurationen für Ihr privates Add-on und eine beliebige Test- oder Entwicklungsumgebung, deren Eigentümer Sie sind, bereitstellen. Das Classroom-Team kann diese Testkonfigurationen vor den Produktionskonfigurationen aktivieren, damit Sie den Ablauf in Ihrer Demodomain testen können. Sie erhalten eine Antwort auf Ihre E-Mail, sobald die Konfigurationen aktiviert wurden. URL-Muster, die localhost verwenden, werden für diese Funktion nicht unterstützt.

Wichtig :Nutzer, die Ihr Add-on installieren und verwenden können, können Links auf Add-on-Anhänge aktualisieren, sobald die Konfigurationen vom Classroom-Team aktiviert wurden. Aus diesem Grund ist es wichtig, zuerst Konfigurationen für das Test-Add-on in einer Test- oder Entwicklungsumgebung bereitzustellen, bevor Sie Produktionskonfigurationen bereitstellen.

Die E-Mail muss 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 ist die URL, die im iFrame für die Link-Umstellung geöffnet werden soll.
• HOST_1: ein Host, der von Classroom erkannt werden soll. Es wird nur das Schema https unterstützt.
• PATH_PREFIX_1 und PATH_PREFIX_2: Pfadpräfixe für HOST_1, die Classroom erkennen und versuchen soll, ein Upgrade durchzuführen.
• HOST_2: ein Host, der von Classroom erkannt werden soll. Es wird nur das Schema https unterstützt.
• PATH_PREFIX_3 und PATH_PREFIX_4: Pfadpräfixe für HOST_2, die Classroom erkennen und versuchen soll, ein Upgrade durchzuführen.

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 bei Bedarf zu vereinfachen oder eine Ladeanzeige einzublenden. Für eine optimale Nutzererfahrung sollte die Lehrkraft nicht zur Eingabe weiterer Informationen aufgefordert 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 den iFrame für das Link-Upgrade verwenden, um zusätzliche Informationen zu erfassen, die Sie benötigen. Über den iFrame kann die Lehrkraft auch informiert werden, wenn kein Upgrade der Verknüpfung möglich ist oder wenn ein Fehler aufgetreten ist.

Nutzerfreundliche Fehlermeldungen beim Zugriff hinzufügen

Wenn Lehrkräfte einen Link einfügen und aktualisieren, auf den sie keinen Zugriff haben, wird im iFrame eine nutzerfreundliche Fehlermeldung angezeigt, damit die Lehrkräfte ü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 erteilen.