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

Un modo in cui gli insegnanti aggiungono contenuti di terze parti a Classroom è incollando un link come Allegato link nella pagina di creazione del compito. Per basarti su ciò che gli insegnanti conoscono già, ora puoi configurare il tuo componente aggiuntivo per consentire loro di eseguire l'upgrade di un allegato di un link a un allegato di un componente aggiuntivo.

Panoramica

Se configuri il componente aggiuntivo con questa funzionalità, agli insegnanti viene richiesto di eseguire l'upgrade di un link all'allegato di un componente aggiuntivo quando incollano un allegato nella pagina di creazione dei compiti. Gli insegnanti vengono invitati a 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, l'iframe dell'upgrade dei link viene lanciato 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 riflettono i parametri di query lanciati nell'iframe di rilevamento degli allegati. Il parametro di query urlToUpgrade è nuovo e può aiutarti a valutare come creare l'allegato del componente aggiuntivo. Quindi, 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 tecnici sull'implementazione

Questa sezione evidenzia alcuni importanti dettagli tecnici della funzionalità.

Leggi il parametro di query urlToUpgrade

Il parametro di query urlToUpgrade è codificato in URI quando viene passato nell'iframe dell'upgrade dei link. Devi decodificare l'URL per ottenerlo nella sua forma originale. Se utilizzi JavaScript, ad esempio, puoi usare la funzione decodeURIComponent() per farlo.

Per garantire un'esperienza utente ottimale per questa funzionalità, invia un postMessage dopo la creazione dell'allegato del componente aggiuntivo. 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 del 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 provare a 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 alcun prefisso di percorso, sarà 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 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 del prefisso del percorso corrisponde a un solo componente e non corrisponde 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 a /123/456/.

Processo di sviluppo

Invia l'URL dell'iframe dell'upgrade del link e i pattern URL per il componente aggiuntivo di test o produzione inviando un'email a classroom-link-upgrade-external@google.com.

Innanzitutto, puoi fornire le configurazioni per il tuo componente aggiuntivo privato e per qualsiasi ambiente di test o sviluppo di tua proprietà. Il team di Classroom può abilitare queste configurazioni di test prima di abilitare quelle di produzione per consentirti di testare il flusso nel tuo dominio demo. Riceverai una risposta alla tua email quando le configurazioni saranno state abilitate. 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 dovrebbe 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 del percorso associati a HOST_1 che Classroom deve rilevare e provare a 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 provare a eseguire l'upgrade.

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

Evitare il lavoro extra per gli insegnanti

Ti consigliamo vivamente di utilizzare l'iframe per facilitare l'accesso, se necessario, o per visualizzare un indicatore di caricamento. Per una migliore esperienza utente, all'insegnante non dovrebbe essere richiesto 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 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 relativi all'accesso facile da usare

Se gli insegnanti incollano ed eseguono l'upgrade di un link a cui non hanno accesso, mostra un messaggio di errore facile da usare nell'iframe, 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.