Dettagli dei parametri di query e iframe

I componenti aggiuntivi di Classroom vengono caricati all'interno di un iframe per fornire all'utente finale un'esperienza utente comoda e senza interruzioni. Esistono quattro tipi di iframe distinti; consulta le pagine iframe nella directory User journeys per una panoramica dello scopo e dell'aspetto di ogni iframe.

Linee guida sulla sicurezza degli iframe

I partner sono tenuti a seguire le best practice del settore per proteggere il proprio iframe. Per proteggere l'iframe, il nostro team per la sicurezza consiglia quanto segue:

• È richiesto HTTPS. Ti consigliamo vivamente di utilizzare TLS 1.2 o versioni successive e di abilitare HTTP Strict Transport Security. Leggi questo articolo sulla MDN correlato relativo alla Strict Transport Security.

• Attiva Criterio di sicurezza del contenuto rigoroso. Consulta questo articolo di OWASP e l'articolo MDN sui criteri di sicurezza del contenuto correlato.

• Attiva l'attributo Cookie sicuri. Consulta l'attributo HttpOnly e questo articolo sulla gestione dei cookie.

Configurazione URI iframe

L'URI di configurazione degli allegati è quello che viene caricato dall'iframe di rilevamento degli allegati ed è il punto in cui gli insegnanti iniziano il flusso di creazione di allegati aggiuntivi in un post di Classroom. Può essere impostato nella console del progetto Google Cloud. Imposta questo URI nella pagina API e servizio del progetto Google Cloud > SDK Google Workspace Marketplace > Configurazione app.

I prefissi URI degli allegati consentiti vengono utilizzati per convalidare gli URI impostati in AddOnAttachment utilizzando i metodi *.addOnAttachments.create e *.addOnAttachments.patch. La convalida è una corrispondenza di prefisso di stringa letterale e al momento non consente l'uso di caratteri jolly.

Parametri di ricerca

Gli iframe passano le informazioni critiche al componente aggiuntivo sotto forma di parametri di query. Esistono due categorie di parametri: relativi agli allegati e relativi all'accesso.

Parametri correlati agli allegati

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

ID corso

Il valore courseId è un identificatore del corso.

Incluso in tutti gli iframe.

ID articolo

Il valore itemId è un identificatore di Announcement,

CourseWork o CourseWorkMaterial a cui è allegato questo allegato.

Incluso in tutti gli iframe.

Tipo di articolo

Il valore itemType identifica il tipo di risorsa su cui

allegato. Il valore della stringa trasmessa è "announcements", "courseWork" o "courseWorkMaterials".

Incluso in tutti gli iframe.

ID allegato

Il valore attachmentId è un identificatore dell'allegato.

Incluso negli iframe teacherViewUri, studentViewUri e studentWorkReviewUri.

ID invio

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

Incluso in studentWorkReviewUri.

Nota: puoi utilizzare una chiave composita di submissionId e attachmentId per identificare il lavoro dello studente nel caso in cui lo stesso allegato sia assegnato allo stesso studente in diversi corsi. Per maggiori informazioni, vedi Contenuti copiati.

Token del componente aggiuntivo

Il valore addOnToken è un token di autorizzazione utilizzato per

addOnAttachments.create chiamate per creare il componente aggiuntivo.

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

URL di cui eseguire l'upgrade

La presenza del valore urlToUpgrade implica che

l'insegnante ha incluso un allegato del link nel compito e ha accettato di eseguirne l'upgrade a un allegato aggiuntivo. Se non hai ancora configurato questa funzionalità, consulta la guida sull'upgrade dei link agli allegati di componenti aggiuntivi per ulteriori dettagli.

Incluso nell'iframe di upgrade dei link.

Parametri relativi all'accesso

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

Suggerimento di accesso

Il login_hint è un identificatore univoco del profilo Google dell'utente

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

Il parametro login_hint può essere usato in due modi:

1. Trasmetti 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'accesso dell'utente non avviene automaticamente.
2. Dopo che l'utente ha eseguito l'accesso, utilizza questo parametro per confrontare il valore con qualsiasi altro utente che potrebbe avere 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, chiedi all'utente di accedere con un pulsante di accesso con il brand Google.

Incluso in tutti gli iframe.

Nota: sono disponibili ulteriori informazioni sull'implementazione del parametro login_hint e sul flusso di accesso nelle pagine SSO, Accesso senza attriti e Gestire la procedura dettagliata per gli accessi ripetuti.

iframe discovery dell'allegato

Dimensione	Descrizione
Obbligatorie	Sì
URI	Forniti nei metadati del componente aggiuntivo
Parametri di query	courseId, itemId, itemType, addOnToken e login_hint.
Altezza	Altezza della finestra dell'80% meno 60 px per l'intestazione superiore
Larghezza	Massimo 1600 px 90% di larghezza della finestra quando la finestra è larga <= 600 px 80% di larghezza della finestra quando la finestra è > 600 px di larghezza

Esempio di scenario di rilevamento degli allegati

1. Un componente aggiuntivo di Classroom è registrato in Google Workspace Marketplace con un URI di rilevamento dell'allegato di https://example.com/addon.
2. Un insegnante installa questo componente aggiuntivo e crea un nuovo annuncio, compito o materiale in 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 del lavoro all'interno dell'iframe per selezionare un allegato.
5. Al momento della selezione dell'allegato, il componente aggiuntivo invia un elemento postMessage a Classroom per chiudere l'iframe.

iframe TeachingViewUri e studenteViewUri

Dimensione	Descrizione
Obbligatorie	Sì
URI	teacherViewUri o studentViewUri
Parametri di query	courseId, itemId, itemType, attachmentId e login_hint.
Altezza	Altezza della finestra del 100% meno 140 px per l'intestazione superiore
Larghezza	100% larghezza finestra

iframe studenteWorkReviewUri

Dimensione	Descrizione
Obbligatorie	No (determina se si tratta di un allegato di tipo attività)
URI	studentWorkReviewUri
Parametri di query	courseId, itemId, itemType, attachmentId, submissionId e login_hint.
Altezza	Altezza della finestra del 100% meno 168 px per l'intestazione superiore
Larghezza	larghezza della finestra al 100% meno larghezza della barra laterale<>: la barra laterale è di 312 px quando è espansa e di 56 px quando è compressa

Nota: gli insegnanti possono aprire l'iframe della revisione del lavoro dello studente per uno studente che non ha mai visualizzato l'allegato del componente aggiuntivo. In questo caso, il componente aggiuntivo potrebbe non essere ancora a conoscenza dello studente e dovrebbe mostrare un messaggio appropriato.

Esegui l'upgrade del link iframe

Dimensione	Descrizione
Obbligatorie	Sì, se il componente aggiuntivo supporta l'upgrade dei link agli allegati dei componenti aggiuntivi.
URI	Forniti nei metadati del componente aggiuntivo
Parametri di query	courseId, itemId, itemType, addOnToken, urlToUpgrade e login_hint.
Altezza	Altezza della finestra dell'80% meno 60 px per l'intestazione superiore
Larghezza	Massimo 1600 px 90% di larghezza della finestra quando la finestra è larga <= 600 px 80% di larghezza della finestra quando la finestra è > 600 px di larghezza

Esempio di scenario di upgrade del link

1. Un componente aggiuntivo di Classroom è registrato con un URI di upgrade del link https://example.com/upgrade. Hai fornito i seguenti pattern del prefisso host e del percorso per gli allegati dei link che Classroom dovrebbe tentare di eseguire l'upgrade a un allegato aggiuntivo:
   • L'host è example.com e il prefisso del percorso è /quiz.
2. Un insegnante crea un nuovo annuncio, compito o materiale all'interno di 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 Allegato del link che corrisponde a un pattern URL da te fornito. All'insegnante viene quindi chiesto di eseguire l'upgrade del link a un allegato aggiuntivo.

4. Classroom avvia l'iframe di upgrade dei link 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. Devi valutare i parametri di query trasmessi nell'iframe ed effettuare una chiamata all'endpoint CreateAddOnAttachment. Tieni presente che il parametro di query urlToUpgrade è codificato con URI quando viene passato nell'iframe. Devi decodificare il parametro per ottenerlo nella forma originale. JavaScript, ad esempio, offre la funzione decodeURIComponent().

6. Una volta creata correttamente l'allegato di un componente aggiuntivo da un link, invii una 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 dalla porta host_name + porta corrispondente all'URI originale che è stato aperto.

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

Chiudere 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 è reindirizzare a una pagina sul dominio originale che non fa altro che inviare l'evento postMessage.

Chiudere l'iframe da una nuova scheda

Le protezioni interdominio impediscono che questa operazione funzioni. Una soluzione alternativa consiste nel gestire autonomamente le comunicazioni tra iframe e nuova scheda e lasciare che l'iframe sia responsabile dell'emissione dell'evento postMessage di chiusura. Ti ricordiamo che il link ipertestuale "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 complica la gestione di una sessione a cui è stato eseguito l'accesso in un iframe. Per informazioni sullo stato attuale del blocco dei cookie nei diversi browser, consulta la pagina https://www.cookiestatus.com. Ovviamente, questo problema non riguarda esclusivamente i componenti aggiuntivi di Google Classroom e riguarda tutti i siti web di terze parti di iframe. 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 di accedere ai cookie creati in un contesto proprietario in un contesto di terze parti.
• Chiedi all'utente di consentire i cookie di terze parti. Ciò potrebbe non essere sempre possibile per tutti gli utenti.
• Progetta applicazioni web su una sola pagina che non si basino sui cookie.

Nelle versioni future del browser sono previste maggiori limitazioni relative ai cookie. Crea richieste di funzionalità per inviare feedback a Google su come ridurre l'incremento richiesto dai partner.

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

Gli insegnanti creano spesso compiti con link allegati. Per promuovere l'utilizzo del tuo componente aggiuntivo, puoi specificare espressioni regolari che corrispondono agli URL delle risorse a cui è possibile accedere nel componente aggiuntivo. Un insegnante che allega un link corrispondente a una delle tue espressioni regolari vede una finestra di dialogo ignorabile che lo invita a provare il tuo componente aggiuntivo. La finestra di dialogo viene visualizzata 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 fornite sono eccessivamente ampie o sono in conflitto con un altro componente aggiuntivo, potrebbero essere modificate per essere più limitate o distinte.

Figura 1. un insegnante seleziona un link allegato a 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 presentata all'insegnante quando il link incollato corrisponde a un'espressione regolare specificata dallo sviluppatore di terze parti.

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