Détails des cadres iFrame et des paramètres de requête

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 de Announcement,

CourseWork ou CourseWorkMaterial auquel ce rattachement est associé.

Inclus dans tous les iFrames.

Type d'élément

La valeur itemType identifie le type de ressource sur lequel

est 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 et studentWorkReviewUri.

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.

Remarque :Vous pouvez utiliser une clé composite de submissionId et attachmentId pour identifier le travail de l'élève si la même pièce jointe est attribuée au même élève dans différents cours. Pour en savoir plus, consultez la section Contenu copié.

Jeton du module complémentaire

La valeur addOnToken est un jeton d'autorisation utilisé pour créer

addOnAttachments.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 que

L'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'utilisateur

un 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:

1. 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.
2. 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.

Remarque :Pour en savoir plus sur l'implémentation du paramètre login_hint et le flux de connexion, consultez les pages SSO, Connexion simplifiée et Tutoriel de gestion des connexions répétées.

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

1. 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.
2. 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 et courseId=123.
3. Lors de la configuration de cet élément, l'enseignant sélectionne le module complémentaire nouvellement installé en pièce jointe.
4. 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.
   1. L'enseignant sélectionne une pièce jointe dans l'iFrame.
5. 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

Remarque :Les enseignants peuvent ouvrir l'iFrame de révision des devoirs des élèves pour un élève qui n'a pas encore consulté la pièce jointe de module complémentaire. Dans ce cas, le module complémentaire ne connaît peut-être pas encore cet élève et doit afficher un message approprié.

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

1. 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.
2. Un enseignant crée une annonce, un devoir ou un support dans l'un de ses cours. Par exemple, itemId=234, itemType=courseWork et courseId=123.
3. 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.

4. 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.

5. 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ête urlToUpgrade 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 fonction decodeURIComponent().

6. 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.