Dettagli dei parametri di query e iframe

I componenti aggiuntivi di Classroom vengono caricati all'interno di un iframe per offrire all'utente finale un'esperienza utente fluida e pratica. Esistono cinque tipi di iframe distinti. Consulta le pagine sugli iframe nella directory User journeys per una panoramica dello scopo e dell'aspetto di ciascun iframe.

Linee guida per la sicurezza degli iframe

Gli sviluppatori sono tenuti a seguire le best practice del settore per proteggere il proprio iframe. Tuttavia, devi anche incorporare determinate interazioni API nel flusso utente per verificare di disporre di credenziali valide e di poter identificare correttamente il ruolo dell'utente nel corso.

Configurazione dell'applicazione server

Per proteggere l'iframe, ti consigliamo le seguenti configurazioni del server:

• È richiesto HTTPS. Consigliamo vivamente di utilizzare TLS 1.2 o versioni successive e di attivare HTTP Strict Transport Security (HSTS). Consulta questo articolo MDN correlato su Strict Transport Security.
• Attiva il criterio di sicurezza del contenuto (CSP) rigoroso. Consulta questo articolo OWASP e questo articolo MDN su Content Security Policy correlato.
• Attiva l'attributo cookie sicuro. Consulta l'attributo HttpOnly e questo articolo MDN sui cookie correlato.

Parametri di query

Gli iframe trasmettono informazioni critiche al componente aggiuntivo come parametri di ricerca. Esistono due categorie di parametri: quelli correlati agli allegati e quelli correlati all'accesso.

Parametri correlati agli allegati

I parametri relativi agli allegati forniscono al componente aggiuntivo informazioni sul corso, sul compito, sull'allegato del componente aggiuntivo, sull'invio dello studente e su un token di autorizzazione.

ID corso

Il valore courseId è un identificatore del corso.

Inclusi in tutti gli iframe.

ID articolo

Il valore itemId è un identificatore di Announcement, CourseWork o CourseWorkMaterial a cui è allegato questo allegato.

Inclusi in tutti gli iframe.

Tipo di elemento

Il valore itemType identifica il tipo di risorsa a cui è allegato questo allegato. Il valore della stringa passato è uno tra "announcements", "courseWork" o "courseWorkMaterials".

Inclusi in tutti gli iframe.

ID allegato

Il valore attachmentId è un identificatore dell'allegato.

Inclusi negli iframe teacherViewUri, studentViewUri e studentWorkReviewUri.

ID invio

Il valore submissionId è un identificatore del lavoro dello studente, ma deve essere utilizzato in combinazione con attachmentId per identificare il lavoro dello studente di un determinato compito.

Incluso con studentWorkReviewUri.

Token del componente aggiuntivo

Il valore addOnToken è un token di autorizzazione utilizzato per effettuare chiamate addOnAttachments.create al fine di creare il componente aggiuntivo.

Incluso nell'iframe di rilevamento degli allegati e nell'iframe di upgrade dei link.

URL da aggiornare

La presenza del valore urlToUpgrade implica che l'insegnante ha incluso un allegato di link nel compito e ha accettato di eseguire l'upgrade a un allegato del componente aggiuntivo. Se non hai ancora configurato questa funzionalità, consulta la guida sull'upgrade dei link per aggiungere allegati componenti aggiuntivi per maggiori dettagli.

Incluso nell'iframe Link Upgrade.

Parametri correlati all'accesso

Il parametro di ricerca login_hint fornisce informazioni sull'utente di Classroom che visita la pagina web del componente aggiuntivo. Questo parametro di query viene fornito nell'URL dell'iframe src. Viene inviato quando l'utente ha utilizzato in precedenza il tuo componente aggiuntivo per ridurre le difficoltà di accesso per gli utenti finali. Devi gestire questo parametro di query nell'implementazione del componente aggiuntivo.

Suggerimento per l'accesso

login_hint è un identificatore univoco dell'Account Google dell'utente. Dopo che l'utente ha eseguito l'accesso al tuo componente aggiuntivo per la prima volta, il parametro login_hint viene trasmesso a ogni visita successiva al tuo componente aggiuntivo da parte dello stesso utente.

Esistono due potenziali utilizzi per il parametro login_hint:

1. Passa il valore login_hint durante il flusso di autenticazione in modo che l'utente non debba inserire le proprie credenziali quando viene visualizzata la finestra di dialogo di accesso. L'utente non accede automaticamente.
2. Dopo che l'utente ha eseguito l'accesso, utilizza questo parametro per confrontare il valore con gli utenti che potrebbero aver già eseguito l'accesso al componente aggiuntivo. Se trovi una corrispondenza, puoi lasciare l'utente connesso ed evitare di mostrare un flusso di accesso. Se il parametro non corrisponde a nessuno degli utenti che hanno eseguito l'accesso, invita l'utente ad accedere con un pulsante di accesso con il brand Google.

Inclusi in tutti gli iframe.

Iframe di rilevamento degli allegati

Scenario di esempio di rilevamento degli allegati

1. Un componente aggiuntivo di Classroom è registrato in Google Workspace Marketplace con un URI di rilevamento degli allegati di https://example.com/addon.
2. Un insegnante installa questo componente aggiuntivo e crea un nuovo annuncio, compito o materiale all'interno di uno dei suoi corsi. Ad esempio, itemId=234, itemType=courseWork e courseId=123.
3. Durante la configurazione dell'elemento, l'insegnante sceglie il componente aggiuntivo appena installato come allegato.
4. Classroom crea un iframe con l'URL src impostato su https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. L'insegnante esegue un'operazione all'interno dell'iframe per selezionare un allegato.
5. Al momento della selezione dell'allegato, il componente aggiuntivo invia un postMessage a Classroom per chiudere l'iframe.

iframe teacherViewUri e studentViewUri

iframe studentWorkReviewUri

Iframe per l'upgrade dei link

Scenario di esempio di upgrade dei link

1. Un componente aggiuntivo di Classroom è registrato con un URI di upgrade del link di https://example.com/upgrade. Hai fornito i seguenti pattern di prefisso di host e percorso per gli allegati di link che Classroom deve tentare di eseguire l'upgrade a un allegato del componente aggiuntivo:
   • L'host è example.com e il prefisso percorso è /quiz.
2. Un insegnante crea un nuovo annuncio, compito o materiale in uno dei suoi corsi. Ad esempio, itemId=234, itemType=courseWork e courseId=123.
3. Un insegnante incolla un link, https://example.com/quiz/5678, nella finestra di dialogo dell'allegato Link che corrisponde a un pattern URL che hai fornito. L'insegnante viene quindi invitato a eseguire l'upgrade del link a un allegato di componenti aggiuntivi.

4. Classroom avvia l'iframe Link Upgrade con l'URL impostato su https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Valuta i parametri di query passati nell'iframe ed effettua una chiamata all'endpoint CreateAddOnAttachment. Tieni presente che il parametro di query urlToUpgrade viene codificato URI quando viene passato nell'iframe. Devi decodificare il parametro per ottenerlo nella sua forma originale. JavaScript, ad esempio, offre la funzione decodeURIComponent().

6. Una volta creato correttamente un allegato del componente aggiuntivo da un link, invii un postMessage a Classroom per chiudere l'iframe.

Chiudi l'iframe

L'iframe può essere chiuso dallo strumento di apprendimento inviando un postMessage con il payload {type: 'Classroom', action: 'closeIframe'}. Classroom accetta questo postMessage solo da host_name+port corrispondente all'URI originale aperto.

<button id="close">Send message to close iframe</button> <script>   document.querySelector('#close')     .addEventListener('click', () => {         window.parent.postMessage({             type: 'Classroom',             action: 'closeIframe',         }, '*');     }); </script> 

Chiudi l'iframe dall'iframe

Il dominio+porta della pagina che invia l'evento postMessage deve avere lo stesso dominio+porta dell'URI utilizzato per avviare l'iframe, altrimenti il messaggio viene ignorato. Una soluzione alternativa consiste nel reindirizzare a una pagina del dominio originale che non fa altro che inviare l'evento postMessage.

Chiudere l'iframe da una nuova scheda

Le protezioni cross-domain impediscono il funzionamento. Una soluzione alternativa consiste nel gestire autonomamente le comunicazioni tra l'iframe e la nuova scheda e lasciare che l'iframe sia il responsabile finale dell'emissione dell'evento di chiusura postMessage. Come nota a margine, l'hyperlink"Apri in Nome partner" verrà rimosso in modo che gli utenti non creino schede in questo modo nel prossimo futuro.

Restrizioni

Tutti gli iframe vengono aperti con i seguenti attributi sandbox:

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

e le seguenti norme relative alle funzionalità:

• allow="microphone *"

Blocco dei cookie di terze parti

Tieni presente che il blocco dei cookie di terze parti rende difficile mantenere una sessione con accesso eseguito in un iframe. Consulta la pagina https://www.cookiestatus.com per lo stato attuale del blocco dei cookie nei diversi browser. Naturalmente, questo problema non riguarda solo i componenti aggiuntivi di Google Classroom e interessa tutti i siti web che incorporano iframe di terze parti. Molti dei nostri partner hanno già riscontrato questo problema.

Ecco alcune soluzioni alternative generali:

• Apri una nuova scheda per creare il cookie in un contesto proprietario. Alcuni browser consentono l'accesso ai cookie creati nel contesto proprietario mentre si trovano in un contesto di terze parti.
• Chiedi all'utente di consentire i cookie di terze parti. Potrebbe non essere sempre possibile con tutti gli utenti.
• Progetta applicazioni web su singola pagina che non si basano sui cookie.

Nelle future versioni dei browser sono previste ulteriori limitazioni dei cookie. Crea richieste di funzionalità per inviare feedback a Google su come ridurre l'impegno richiesto ai partner.

Attivare la rilevabilità dei componenti aggiuntivi utilizzando le espressioni regolari degli URL

Gli insegnanti creano spesso compiti con allegati di link. Per promuovere l'utilizzo del tuo componente aggiuntivo, puoi specificare espressioni regolari che corrispondono agli URL delle risorse a cui è possibile accedere nel tuo componente aggiuntivo. Un insegnante che allega un link che corrisponde a una delle tue espressioni regolari visualizza una finestra di dialogo chiudibile che lo incoraggia a provare il tuo componente aggiuntivo. Visualizzano la finestra di dialogo solo se il componente aggiuntivo è già installato per il loro account.

Se vuoi fornire questo comportamento agli insegnanti, fornisci ai tuoi contatti Google le espressioni regolari appropriate. Se le espressioni regolari che fornisci sono troppo ampie o in conflitto con un altro componente aggiuntivo, potrebbero essere modificate per essere più restrittive o distinte.

Figura 1. Insegnante che seleziona un allegato di un link per un nuovo compito.

Figura 2. L'insegnante incolla un link da una fonte di terze parti. L'insegnante ha già installato il componente aggiuntivo di Classroom di terze parti.

Figura 3. La finestra di dialogo interattiva visualizzata dall'insegnante quando il link incollato corrisponde a un'espressione regolare specificata dallo sviluppatore di terze parti.

Se un insegnante seleziona "Prova ora" nel popup mostrato nella figura 3, viene reindirizzato all'iframe di rilevamento degli allegati del tuo componente aggiuntivo.