Un modo in cui gli insegnanti aggiungono contenuti di terze parti a Classroom consiste nell'incollare un link come Allegato del link nella pagina di creazione dei compiti. Per utilizzare le funzionalità già note per gli insegnanti, puoi configurare il componente aggiuntivo in modo da consentire agli insegnanti di eseguire l'upgrade di un link a un allegato del componente aggiuntivo.
Panoramica
Se configuri il componente aggiuntivo con questa funzionalità, agli insegnanti viene chiesto di eseguire l'upgrade di un link a un allegato del componente aggiuntivo quando incollano un allegato nella pagina di creazione dei compiti. Gli insegnanti possono farlo solo se hanno già installato il componente aggiuntivo.
Una volta che l'insegnante ha accettato di eseguire l'upgrade del link a un allegato del componente aggiuntivo, viene avviato l'iframe dell'upgrade dei link con i seguenti parametri di query:
courseId
itemId
(nome cambiato dapostId
)itemType
(novità!)addOnToken
login_hint
ohd
urlToUpgrade
(novità!)
I primi quattro parametri di query rispecchiano quelli lanciati nell'iframe di rilevamento degli allegati. Il parametro di query urlToUpgrade
è nuovo e può aiutarti a valutare come creare il collegamento del componente aggiuntivo. Poi, puoi utilizzare gli altri parametri di query per verificare se l'utente ha eseguito l'accesso e chiamare il metodo CreateAddOnAttachment
di courseWork
, courseWorkMaterials
o announcements
in base al valore itemType
. All'interno dell'iframe puoi visualizzare una schermata di caricamento per indicare all'insegnante che è in corso la creazione dell'allegato del componente aggiuntivo.
Una volta creato l'allegato del componente aggiuntivo, l'iframe viene chiuso e l'insegnante può visualizzare l'allegato nel compito come farebbe normalmente.
Dettagli tecnici di implementazione
Questa sezione evidenzia alcuni importanti dettagli tecnici relativi alla funzionalità.
Leggi il parametro di query urlToUpgrade
Il parametro di query urlToUpgrade
è codificato nell'URI quando viene trasmesso all'iframe
dell'upgrade dei link. È necessario decodificare l'URL per ottenerlo nella sua forma originale. Se
utilizzi JavaScript, ad esempio, puoi utilizzare la
funzione decodeURIComponent()
per farlo.
Chiudi l'iframe dell'upgrade dei link
Per garantire un'esperienza utente ottimale per questa funzionalità, invia un postMessage
dopo aver creato l'allegato del componente aggiuntivo. In questo modo l'iframe viene chiuso. Per ulteriori dettagli, consulta la pagina dei dettagli dell'implementazione dell'iframe.
Dettagli della configurazione
Per integrare questa funzionalità nel componente aggiuntivo, sono necessarie le seguenti configurazioni:
URL per l'iframe dell'upgrade dei link: si tratta dell'URL che si apre nell'iframe quando un insegnante accetta di eseguire l'upgrade.
Pattern URL che Classroom dovrebbe rilevare e tentare di eseguire l'upgrade: i pattern URL possono essere costituiti da un host e da più prefissi di percorso.
- Puoi fornire più pattern URL.
- Se non fornisci prefissi del percorso, è possibile eseguire l'upgrade di qualsiasi URL corrispondente all'host.
- È possibile eseguire l'upgrade solo degli URL con uno schema
https
. - I pattern URL non devono contenere
localhost
. - I prefissi del percorso non devono contenere parametri di query o frammenti di URL.
- Al momento i prefissi del percorso possono supportare i caratteri jolly, ma gli host non possono:
-
example.com
è un host valido, mentre/foo
e/bar/*/baz
sono prefissi di percorso validi. -
example.*.host.com
non è un host valido.
-
- Un carattere jolly tra i componenti prefisso percorso corrisponde a un solo componente e non a più componenti separati da barre.
Considera un pattern URL con l'host
example.com
e il prefisso del percorso/bar/*/baz
:-
https://example.com/bar/123/baz
è una corrispondenza valida per il pattern URL. -
https://example.com/bar/123/baz/456/789
è una corrispondenza valida per il pattern URL. -
https://example.com/bar/123/456/baz
non è una corrispondenza valida per il pattern URL perché il carattere jolly nel prefisso del percorso non corrisponde/123/456/
.
-
Processo di sviluppo
Invia l'URL e i pattern URL dell'iframe dell'upgrade dei link per il tuo componente aggiuntivo di test o di produzione inviando un'email a classroom-link-upgrade-external@google.com.
Puoi innanzitutto fornire le configurazioni per il componente aggiuntivo privato e per qualsiasi ambiente di test o di sviluppo di tua proprietà. Il team di Classroom può attivare queste configurazioni di test prima di abilitare le configurazioni di produzione per consentirti di testare il flusso nel dominio demo. Riceverai una risposta alla tua email
dopo aver abilitato le configurazioni. Tieni presente che i pattern URL che utilizzano localhost
non sono supportati per questa funzionalità.
Formatta l'email in modo che includa quanto segue:
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
Sostituisci quanto segue:
- GCP_PROJECT_NUMBER: il numero del progetto Google Cloud a cui è associato il componente aggiuntivo.
- LINK_UPGRADE_IFRAME_URL l'URL che dovrebbe aprirsi nell'iframe dell'upgrade dei link.
- HOST_1: un host che Classroom dovrebbe rilevare.
È supportato solo lo schema
https
. - PATH_PREFIX_1 e PATH_PREFIX_2:
prefissi del percorso associati a
HOST_1
che Classroom deve rilevare e tentare di eseguire l'upgrade. - HOST_2: un host che Classroom dovrebbe rilevare.
È supportato solo lo schema
https
. - PATH_PREFIX_3e PATH_PREFIX_4:
prefissi del percorso associati a
HOST_2
che Classroom deve rilevare e tentare di eseguire l'upgrade.
Esperienza utente consigliata
Di seguito sono riportati alcuni suggerimenti da considerare durante l'implementazione di questa funzionalità.
Evitare lavoro aggiuntivo per gli insegnanti
Ti consigliamo vivamente di utilizzare l'iframe per facilitare l'accesso, se necessario, o per visualizzare un indicatore di caricamento. Per un'esperienza utente ottimale, all'insegnante non dovrebbe essere chiesto di fornire ulteriori informazioni dopo aver accettato di eseguire l'upgrade del link incollato in un allegato del componente aggiuntivo. Tuttavia, se questo non è possibile per il tuo componente aggiuntivo, puoi utilizzare l'iframe dell'upgrade dei link per raccogliere le informazioni aggiuntive di cui hai bisogno. L'iframe può essere utilizzato anche per informare l'insegnante se non è possibile eseguire l'upgrade del link o se si è verificato un errore.
Includi messaggi di errore di accesso intuitivi
Se gli insegnanti incollano ed eseguono l'upgrade di un link a cui non hanno accesso, nell'iframe vengono visualizzati un messaggio di errore facile da usare, in modo che gli insegnanti siano a conoscenza del problema. L'iframe può essere utilizzato anche per fornire all'insegnante le autorizzazioni appropriate per accedere ai contenuti.