Les modules complémentaires Classroom sont chargés dans un iFrame pour offrir à l'utilisateur final une expérience simple et pratique. Il existe quatre types d'iFrames distincts. Consultez les pages iFrame dans le répertoire "Parcours utilisateur" pour découvrir l'objectif et l'apparence de chaque iFrame.
consignes de sécurité iFrame
Les partenaires doivent respecter les bonnes pratiques du secteur pour sécuriser leur iFrame. Pour protéger l'iFrame, notre équipe de sécurité recommande ce qui suit:
Le protocole HTTPS est requis. Nous vous recommandons vivement d'utiliser TLS 1.2 ou version ultérieure et d'activer HTTP Strict Transport Security. Consultez cet article MDN associé sur Strict Transport Security.
Activez Strict Content Security Policy. Consultez cet article OWASP et l'article associé sur le MDN de Content Security Policy.
Activez l'attribut de cookie sécurisé. Consultez la section sur l'attribut HttpOnly et l'article MDN sur les cookies associé.
Configuration de l'URI iFrame
L'URI de configuration de la pièce jointe correspond au contenu de l'iFrame de découverte des pièces jointes. Il permet aux enseignants de créer des pièces jointes de module complémentaire dans un post Classroom. Vous pouvez le définir dans la console du projet Google Cloud. Définissez cet URI sur la page API et service de votre projet Google Cloud > SDK Google Workspace Marketplace > Configuration de l'application.
Les préfixes d'URI des pièces jointes autorisés permettent de valider les URI définis dans AddOnAttachment à l'aide des méthodes *.addOnAttachments.create
et *.addOnAttachments.patch
. La validation est une correspondance de préfixe de chaîne littérale et ne permet pas l'utilisation de caractères génériques pour le moment.
Paramètres de requête
Les iFrames transmettent des informations critiques au module complémentaire en tant que paramètres de requête. Il existe deux catégories de paramètres: les paramètres liés aux pièces jointes et les paramètres liés à la connexion.
Paramètres liés aux pièces jointes
Les paramètres liés aux pièces jointes fournissent au module complémentaire des informations sur le cours, le devoir, la pièce jointe de module complémentaire, l'envoi de l'élève et un jeton d'autorisation.
- ID du cours
La valeur
courseId
est un identifiant pour le cours.Inclus dans tous les iFrames.
- ID de l'article
La valeur
itemId
est un identifiant deAnnouncement
,CourseWork
ouCourseWorkMaterial
auquel ce rattachement est associé.Inclus dans tous les iFrames.
- Type d'élément
La valeur
itemType
identifie le type de ressource sur lequelest jointe. La valeur de chaîne transmise est
"announcements"
,"courseWork"
ou"courseWorkMaterials"
.Inclus dans tous les iFrames.
- ID de la pièce jointe
La valeur
attachmentId
est un identifiant pour le rattachement.Inclus avec les iFrames
teacherViewUri
,studentViewUri
etstudentWorkReviewUri
.- ID de l'envoi
La valeur
submissionId
est un identifiant associé au devoir de l'élève, mais elle doit être utilisée avec la propriétéattachmentId
pour identifier le travail de l'élève sur un devoir particulier.Inclus avec
studentWorkReviewUri
.
- Jeton du module complémentaire
La valeur
addOnToken
est un jeton d'autorisation utilisé pour créeraddOnAttachments.create
pour créer le module complémentaire.Inclus dans les cadres iFrame de découverte de pièces jointes et iFrame de mise à niveau du lien.
- URL à mettre à jour
La présence de la valeur
urlToUpgrade
implique queL'enseignant a inclus une pièce jointe sous forme de lien dans le devoir et a accepté de la convertir en pièce jointe de module complémentaire. Si cette fonctionnalité n'est pas déjà configurée, consultez le guide sur la mise à niveau des liens vers les pièces jointes de modules complémentaires pour en savoir plus.
Inclus avec l'iFrame de mise à niveau du lien.
Paramètres liés à la connexion
Le paramètre de requête login_hint
fournit des informations sur l'utilisateur Classroom qui accède à la page Web du module complémentaire. Ce paramètre de requête est fourni dans l'URL src
de l'iFrame. Il est envoyé lorsque l'utilisateur a déjà utilisé votre module complémentaire afin de faciliter sa connexion. Vous devez gérer ce paramètre de requête dans la mise en œuvre de votre module complémentaire.
- Indice de connexion
Le
login_hint
est un identifiant unique associé au compte Google de l'utilisateurun compte de service Google. Une fois que l'utilisateur s'est connecté à votre module complémentaire pour la première fois, le paramètre
login_hint
est transmis à chaque visite ultérieure de votre module complémentaire par le même utilisateur.Le paramètre
login_hint
peut être utilisé de deux manières différentes:- Transmettez la valeur
login_hint
lors du flux d'authentification afin que l'utilisateur n'ait pas besoin de saisir ses identifiants lorsque la boîte de dialogue de connexion s'affiche. L'utilisateur n'est pas connecté automatiquement. - Une fois l'utilisateur connecté, utilisez ce paramètre pour comparer la valeur à celle des utilisateurs déjà connectés au module complémentaire. Si vous trouvez une correspondance, vous pouvez laisser l'utilisateur connecté et éviter d'afficher une procédure de connexion. Si le paramètre ne correspond à aucun de vos utilisateurs connectés, invitez-les à se connecter à l'aide d'un bouton de connexion de marque Google.
Inclus dans tous les iFrames.
- Transmettez la valeur
iFrame de découverte de pièces jointes
Dimension | Description |
---|---|
Obligatoire | Oui |
URI | Fourni dans les métadonnées du module complémentaire |
Paramètres de requête | courseId , itemId , itemType , addOnToken et login_hint . |
Taille | 80% de la hauteur de la fenêtre moins 60 px pour l'en-tête supérieur |
Largeur | Maximum de 1 600 px 90% de largeur de la fenêtre si sa largeur est inférieure ou égale à 600 px 80% de largeur de la fenêtre si sa largeur est supérieure à 600 px |
Exemple de scénario de découverte de pièces jointes
- Un module complémentaire Classroom est enregistré dans Google Workspace Marketplace avec l'URI de découverte de pièces jointes
https://example.com/addon
. - Un enseignant installe ce module complémentaire et crée une annonce, un devoir ou un support dans l'un de ses cours. Par exemple,
itemId=234
,itemType=courseWork
etcourseId=123
. - Lors de la configuration de cet élément, l'enseignant sélectionne le module complémentaire nouvellement installé en pièce jointe.
- Classroom crée un iFrame dont l'URL src est définie sur
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- L'enseignant sélectionne une pièce jointe dans l'iFrame.
- Lors de la sélection de la pièce jointe, le module complémentaire envoie un
postMessage
à Classroom pour fermer l'iFrame.
iFrames "TeacherViewUri" et "StudentViewUri"
Dimension | Description |
---|---|
Obligatoire | Oui |
URI | teacherViewUri ou studentViewUri |
Paramètres de requête | courseId , itemId , itemType , attachmentId et login_hint . |
Taille | Hauteur de fenêtre 100% moins 140 px pour l'en-tête supérieur |
Largeur | Largeur de fenêtre 100 % |
Cadre iFrameStudentWorkReviewUri
Dimension | Description |
---|---|
Obligatoire | Non (détermine s'il s'agit d'un rattachement de type activité) |
URI | studentWorkReviewUri |
Paramètres de requête | courseId , itemId , itemType , attachmentId , submissionId et login_hint . |
Taille | Hauteur de la fenêtre totale moins 168 px pour l'en-tête supérieur |
Largeur | Largeur de 100% de la fenêtre moins la largeur de la barre latérale<>, la barre latérale est de 312 pixels lorsqu'elle est développée et de 56 pixels lorsqu'elle est réduite |
iFrame de mise à niveau du lien
Dimension | Description |
---|---|
Obligatoire | Oui, si votre module complémentaire permet de mettre à niveau les liens vers les pièces jointes de module complémentaire. |
URI | Fourni dans les métadonnées du module complémentaire |
Paramètres de requête | courseId , itemId , itemType , addOnToken , urlToUpgrade et login_hint . |
Taille | 80% de la hauteur de la fenêtre moins 60 px pour l'en-tête supérieur |
Largeur | Maximum de 1 600 px 90% de largeur de la fenêtre si sa largeur est inférieure ou égale à 600 px 80% de largeur de la fenêtre si sa largeur est supérieure à 600 px |
Exemple de scénario de mise à niveau d'une association
- Un module complémentaire Classroom est enregistré avec un URI de mise à niveau de lien de
https://example.com/upgrade
. Vous avez fourni les formats de préfixe d'hôte et de chemin d'accès suivants pour les pièces jointes de lien que Classroom doit tenter de convertir en pièce jointe de module complémentaire :- L'hôte est
example.com
et le préfixe de chemin d'accès est/quiz
.
- L'hôte est
- Un enseignant crée une annonce, un devoir ou un support dans l'un de ses cours. Par exemple,
itemId=234
,itemType=courseWork
etcourseId=123
. - Dans la boîte de dialogue "Pièce jointe de lien", un enseignant colle un lien (
https://example.com/quiz/5678
) correspondant au format d'URL que vous avez fourni. L'enseignant est ensuite invité à convertir le lien en pièce jointe de module complémentaire. Classroom lance l'iFrame de mise à niveau du lien dont l'URL est définie sur
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.Vous évaluez les paramètres de requête transmis sur l'iFrame et vous appelez le point de terminaison
CreateAddOnAttachment
. Notez que le paramètre de requêteurlToUpgrade
est encodé en URI lorsqu'il est transmis dans l'iFrame. Vous devez décoder le paramètre pour l'obtenir dans sa forme d'origine. JavaScript, par exemple, propose la fonctiondecodeURIComponent()
.Lorsque vous créez une pièce jointe de module complémentaire à partir d'un lien, vous envoyez un
postMessage
à Classroom pour fermer l'iFrame.
Fermer l'iFrame
L'iFrame peut être fermé à partir de l'outil d'apprentissage en envoyant un postMessage
avec la charge utile {type: 'Classroom', action: 'closeIframe'}
.
Classroom n'accepte que ce postMessage
du nom d'hôte et du port correspondant à l'URI d'origine qui a été ouvert.
<button id="close">Send message to close iframe</button>
<script>
document.querySelector('#close')
.addEventListener('click', () => {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
});
</script>
Fermer l'iFrame à partir de l'iFrame
Le domaine et le port de la page envoyant l'événement postMessage
doivent être identiques à ceux de l'URI utilisé pour lancer l'iFrame. Sinon, le message est ignoré. Une solution de contournement consiste à rediriger l'utilisateur vers une page du domaine d'origine, qui se contente d'envoyer l'événement postMessage
.
Fermer l'iFrame à partir d'un nouvel onglet
Les protections multidomaines empêchent cela de fonctionner. Une solution de contournement consiste à gérer vous-même les communications entre l'iFrame et le nouvel onglet, et à laisser l'iFrame se charger de l'émission de l'événement de fermeture postMessage
. Notez que le lien hypertexte "Ouvrir dans le nom du partenaire" est supprimé afin que les utilisateurs ne créent pas d'onglets de cette manière dans un avenir proche.
Restrictions
Tous les iFrames sont ouverts avec les attributs de bac à sable suivants:
allow-popups
allow-popups-to-escape-sandbox
allow-forms
allow-scripts
allow-storage-access-by-user-activation
allow-same-origin
et la règle de caractéristiques
allow="microphone *"
Blocage des cookies tiers
Sachez que le blocage des cookies tiers rend difficile le maintien d'une session connectée dans un iFrame. Consultez la page https://www.cookiestatus.com pour connaître l'état actuel du blocage des cookies sur les différents navigateurs. Bien sûr, ce problème n'est pas propre aux modules complémentaires Google Classroom et concerne tous les sites Web qui intègrent des cadres iFrame tiers. Un grand nombre de nos partenaires ont déjà rencontré ce problème.
Voici quelques solutions générales:
- Ouvrez un nouvel onglet pour créer le cookie dans un contexte propriétaire. Certains navigateurs autorisent l'accès aux cookies créés dans un contexte propriétaire dans un contexte tiers.
- Demandez à l'utilisateur d'autoriser les cookies tiers. Cela n'est pas toujours possible pour tous les utilisateurs.
- Concevez des applications Web monopages qui ne reposent pas sur des cookies.
D'autres restrictions liées aux cookies sont attendues dans les prochaines versions des navigateurs. Créez des demandes de fonctionnalités pour envoyer des commentaires à Google sur la façon de réduire l'impact requis par les partenaires.
Activer la visibilité des modules complémentaires à l'aide d'expressions régulières d'URL
Les enseignants créent fréquemment des devoirs comportant des pièces jointes sous forme de liens. Pour promouvoir l'utilisation de votre module complémentaire, vous pouvez spécifier des expressions régulières correspondant aux URL des ressources accessibles dans le module complémentaire. Un enseignant qui joint un lien qui correspond à l'une de vos expressions régulières voit s'afficher une boîte de dialogue qu'il peut ignorer, l'encourageant à essayer votre module complémentaire. La boîte de dialogue ne s'affiche que si le module complémentaire est déjà installé pour son compte.
Si vous souhaitez proposer ce comportement aux enseignants, fournissez à vos contacts Google les expressions régulières appropriées. Si les expressions régulières que vous fournissez sont trop larges ou entrent en conflit avec un autre module complémentaire, elles peuvent être modifiées pour être plus limitées ou distinctes.
Figure 1. en sélectionnant un lien vers un nouveau devoir.
Figure 2. en collant un lien provenant d'une source tierce. L'enseignant a déjà installé le module complémentaire Classroom du tiers.
Figure 3. Boîte de dialogue interactive présentée à l'enseignant lorsque le lien collé correspond à une expression régulière spécifiée par le développeur tiers.
Si un enseignant sélectionne "Essayer maintenant" dans la fenêtre pop-up, comme illustré dans la figure 3, il est redirigé vers l'iFrame de découverte de pièces jointes du module complémentaire.