I componenti aggiuntivi di Google Classroom sono ora in disponibilità generale per gli sviluppatori. Per ulteriori informazioni, consulta la documentazione relativa ai componenti aggiuntivi.

Questa pagina è stata tradotta dall'API Cloud Translation.

Eseguire l'upgrade degli allegati Link agli allegati del componente aggiuntivo di Classroom

Un modo in cui gli insegnanti possono aggiungere contenuti di terze parti a Classroom è incollando un link come Allegato link nella pagina di creazione del compito. Per fare tesoro delle conoscenze già acquisite dagli insegnanti, ora puoi configurare il tuo componente aggiuntivo in modo che consenta agli insegnanti di eseguire l'upgrade di un allegato link a un allegato del componente aggiuntivo.

Panoramica

Se configuri il tuo 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 del link nella pagina di creazione del compito. Agli insegnanti viene chiesto di farlo solo se hanno già installato il componente aggiuntivo.

Una volta che l'insegnante accetta di eseguire l'upgrade del link a un allegato del componente aggiuntivo, viene avviato l'iframe di Link Upgrade con i seguenti parametri di query:

courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint (solo se l'utente ha già autorizzato la tua app)

I primi quattro parametri di query rispecchiano i parametri di query lanciati nell'iframe di Discovery degli allegati. Il parametro di query urlToUpgrade è nuovo e può aiutarti a valutare come deve essere creato il 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 l'allegato del componente aggiuntivo è in fase di creazione.

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 sull'implementazione tecnica

Questa sezione evidenzia alcuni dettagli tecnici importanti della funzionalità.

Leggi il parametro di query `urlToUpgrade`

Il parametro di query urlToUpgrade è codificato in URI quando viene trasmesso nell'iframe di upgrade del link. Devi decodificare l'URL per ottenerlo nella sua forma originale. Ad esempio, se utilizzi JavaScript, puoi utilizzare la funzione decodeURIComponent().

Chiudi l'iframe di upgrade del link

Per garantire un'esperienza utente ottimale per questa funzionalità, invia un postMessage una volta creato correttamente il componente aggiuntivo allegato. L'iframe viene chiuso. Per ulteriori dettagli, consulta la pagina dei dettagli sull'implementazione degli iframe.

Dettagli configurazione

Per integrare questa funzionalità nel tuo componente aggiuntivo, sono necessarie le seguenti configurazioni:

URL per l'iframe di aggiornamento del link: si tratta dell'URL che si apre nell'iframe quando un insegnante accetta 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 di percorso, è possibile eseguire l'upgrade di qualsiasi URL che corrisponda all'host.
- È possibile eseguire l'upgrade solo degli URL con uno schema https.
- I pattern URL non devono contenere localhost.
- I prefissi dei percorsi non devono contenere parametri di query o frammenti di URL.
- Al momento i prefissi dei percorsi possono supportare i caratteri jolly, ma non gli host:
  - example.com è un host valido e /foo e /bar/*/baz sono prefissi di percorso validi.
  - example.*.host.com non è un host valido.
- Un carattere jolly tra i componenti del prefisso del percorso corrisponde a un solo componente e non a più componenti separati da barre. Prendi in considerazione 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 iframe e i pattern URL dell'upgrade del link per il tuo componente aggiuntivo di test o di produzione inviando un'email all'indirizzo classroom-link-upgrade-external@google.com.

Puoi fornire configurazioni per qualsiasi progetto Google Cloud che rappresenti un plug-in di Classroom. Ti consigliamo di fornire prima le configurazioni per un componente aggiuntivo con visibilità privata in modo da poterlo sviluppare e testare in un dominio demo senza influire sugli utenti reali.

Riceverai una risposta alla tua email quando le configurazioni saranno state attivate. Tieni presente che i pattern URL che utilizzano localhost non sono supportati per questa funzionalità.

Formatta l'email in modo da includere 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 deve aprirsi nell'iframe di Link Upgrade.
HOST_1: un host che Classroom dovrebbe rilevare. È supportato solo lo schema https.
PATH_PREFIX_1 e PATH_PREFIX_2: prefissi di percorso associati a HOST_1 che Classroom dovrebbe rilevare e tentare di eseguire l'upgrade.
HOST_2: un host che Classroom dovrebbe rilevare. È supportato solo lo schema https.
PATH_PREFIX_3 e PATH_PREFIX_4: prefissi di percorso associati a HOST_2 che Classroom dovrebbe rilevare e tentare di eseguire l'upgrade.

Esperienza utente consigliata

Di seguito sono riportati alcuni suggerimenti da prendere in considerazione durante l'implementazione di questa funzionalità.

Evitare un lavoro extra per gli insegnanti

Ti consigliamo vivamente di utilizzare l'iframe per semplificare l'accesso, se necessario, o per visualizzare un indicatore di caricamento. Per un'esperienza utente ottimale, all'insegnante non deve essere chiesto di fornire ulteriori informazioni dopo aver accettato di eseguire l'upgrade del link incollato in un allegato del componente aggiuntivo. Tuttavia, se non è possibile per il tuo componente aggiuntivo, puoi utilizzare l'iframe di Link Upgrade 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 facili da comprendere

Se gli insegnanti incollano e eseguono l'upgrade di un link a cui non hanno accesso, nell'iframe viene visualizzato un messaggio di errore intuitivo per informarli del problema. L'iframe può essere utilizzato anche per fornire all'insegnante le autorizzazioni appropriate per accedere ai contenuti.