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

Les modules complémentaires Classroom sont chargés dans un iFrame afin d'offrir à l'utilisateur final une expérience fluide 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 sont tenus de 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 une version ultérieure et d'activer HTTP Strict Transport Security. Consultez cet article du MN sur la sécurité stricte du transport en termes de sécurité.

• Activez la règle Strict Content Security Policy. Consultez cet article OWASP et cet article MDN sur Content Security Policy.

• Activez l'attribut de cookie sécurisé. Consultez l'attribut HttpOnly et l'article MDN sur les cookies associé.

Configuration de l'URI iFrame

L'URI de configuration des pièces jointes correspond à ce que charge l'iFrame de découverte des pièces jointes. C'est à ce niveau que les enseignants commencent à créer des pièces jointes de modules complémentaires dans un post Classroom. Il peut être défini dans la console de projet Google Cloud. Définissez cet URI sur la page API et service > SDK Google Workspace Marketplace > Configuration de l'application de votre projet Google Cloud.

Les préfixes d'URI de 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 d'utiliser des 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 avec tous les iFrames.

ID du post (obsolète)

La valeur postId est un identifiant du post (annonce, devoir ou support de cours) auquel cette pièce jointe est jointe.

Inclus avec tous les iFrames.

Obsolète:l'ID de l'article est désormais obsolète. Utilisez plutôt l'ID de l'article.

ID de l'article

La valeur itemId est un identifiant des éléments Announcement, CourseWork ou CourseWorkMaterial auxquels ce rattachement est associé.

Inclus avec tous les iFrames.

Type d'élément

La valeur itemType identifie le type de ressource auquel ce rattachement est associé. La valeur de chaîne transmise est "announcements", "courseWork" ou "courseWorkMaterials".

Inclus avec 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 d'envoi

La valeur submissionId est un identifiant pour le travail de l'élève, mais doit être utilisée avec la valeur attachmentId pour identifier le travail de l'élève pour un devoir particulier.

Inclus avec le studentWorkReviewUri.

Remarque :Vous pouvez utiliser une clé composite de submissionId et de attachmentId pour identifier le travail d'un é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 sur le contenu copié.

Jeton complémentaire

La valeur addOnToken est un jeton d'autorisation utilisé pour effectuer des appels addOnAttachments.create afin de créer le module complémentaire.

Inclus dans l'iFrame de découverte des pièces jointes et dans l'iFrame de mise à niveau du lien.

URL à mettre à jour

La valeur urlToUpgrade signifie que l'enseignant a inclus une pièce jointe de lien dans le devoir et qu'il a accepté de la convertir en pièce jointe de module complémentaire. Si cette fonctionnalité n'est pas encore 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 de lien.

Paramètres de 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 réduire les problèmes de connexion. Vous devez gérer ce paramètre de requête dans l'implémentation de votre module complémentaire.

Indice pour la connexion

Le login_hint est un identifiant unique pour le compte Google

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 par le même utilisateur lors de chaque visite ultérieure de votre module complémentaire.

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 pour lesquels vous vous êtes peut-être déjà connecté au module complémentaire. Si une correspondance est trouvée, vous pouvez laisser l'utilisateur connecté et éviter d'afficher un flux 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 Google.

Inclus avec 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 Authentification unique, Guide de connexion simplifiée et Gérer les connexions répétées.

iFrame de découverte des pièces jointes

Dimension	Description
Obligatoire	Oui
URI	Fournies dans les métadonnées du module complémentaire
Paramètres de requête	courseId, postId (obsolète), itemId, itemType, addOnToken et login_hint.
Taille	Hauteur de la fenêtre 80% moins 60 px pour l'en-tête supérieur
Largeur	1 600 pixels maximum 90% de largeur de fenêtre lorsque la fenêtre est inférieure ou égale à 600 pixels de large 80% de largeur de fenêtre lorsqu'elle dépasse 600 pixels de large

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 des 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. Exemples : itemId=234, itemType=courseWork et courseId=123.
3. Lors de la configuration de cet élément, l'enseignant choisit le module complémentaire nouvellement installé en tant que 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 effectue un travail dans l'iFrame pour sélectionner une pièce jointe.
5. Lorsqu'une pièce jointe est sélectionnée, 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, postId (obsolète), itemId, itemType, attachmentId et login_hint.
Taille	100% de hauteur de la fenêtre moins 140 pixels pour l'en-tête supérieur
Largeur	Largeur de la fenêtre 100 %

iFrame étudiantsWorkReviewUri

Dimension	Description
Obligatoire	Non (détermine s'il s'agit d'une pièce jointe de type activité)
URI	studentWorkReviewUri
Paramètres de requête	courseId, postId (obsolète), itemId, itemType, attachmentId, submissionId et login_hint.
Taille	Hauteur de la fenêtre 100% moins 168 px pour l'en-tête supérieur
Largeur	100% de la largeur de la fenêtre moins la largeur de 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 "Révision des devoirs des élèves" pour un élève qui n'a pas encore affiché la pièce jointe du module complémentaire. Dans ce cas, il est possible que le module complémentaire ne connaisse pas encore cet élève et affiche un message approprié.

iFrame de mise à niveau du lien

Dimension	Description
Obligatoire	Oui, si votre module complémentaire accepte la mise à niveau des liens vers les pièces jointes de modules complémentaires.
URI	Fournies dans les métadonnées du module complémentaire
Paramètres de requête	courseId, postId (obsolète), itemId, itemType, addOnToken, urlToUpgrade et login_hint.
Taille	Hauteur de la fenêtre 80% moins 60 px pour l'en-tête supérieur
Largeur	1 600 pixels maximum 90% de largeur de fenêtre lorsque la fenêtre est inférieure ou égale à 600 pixels de large 80% de largeur de fenêtre lorsqu'elle dépasse 600 pixels de large

Exemple de scénario de mise à niveau des liens

1. Un module complémentaire Classroom est enregistré avec l'URI de mise à niveau du lien 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 liens que Classroom doit tenter de convertir en pièce jointe de module complémentaire :
   • L'hôte est example.com, et le préfixe du chemin d'accès est /quiz.
2. Un enseignant crée une annonce, un devoir ou un support dans l'un de ses cours. Exemples : itemId=234, itemType=courseWork et courseId=123.
3. Un enseignant colle dans la boîte de dialogue https://example.com/quiz/5678 un lien qui correspond 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 avec l'URL définie sur https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Vous évaluez les paramètres de requête transmis à l'iFrame et 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. Lorsqu'une pièce jointe de module complémentaire à partir d'un lien a bien été créée, vous envoyez un postMessage à Classroom pour fermer l'iFrame.

Fermer l'iFrame

Vous pouvez fermer l'iFrame à 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 qui envoie l'événement postMessage doivent avoir le même domaine et port que l'URI utilisé pour lancer l'iFrame. Sinon, le message est ignoré. Une solution de contournement consiste à rediriger les utilisateurs vers une page du domaine d'origine qui se contente d'envoyer l'événement postMessage.

Fermer l'iFrame depuis 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 être responsable de l'émission de l'événement de fermeture postMessage. Par ailleurs, le lien hypertexte "Ouvrir dans le nom du partenaire" sera 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 les règles de caractéristiques suivantes

• allow="microphone *"

Blocage des cookies tiers

Sachez que le blocage des cookies tiers rend difficile la gestion d'une session connectée dans un iFrame. Pour connaître l'état actuel du blocage des cookies dans différents navigateurs, consultez https://www.cookiestatus.com. Bien entendu, ce problème n'est pas propre aux modules complémentaires Google Classroom et concerne tous les sites Web qui intègrent des cadres 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 avec tous les utilisateurs.
• Concevez des applications Web monopages qui ne reposent pas sur les cookies.

Davantage de restrictions concernant les cookies sont prévues dans les futures versions des navigateurs. Créez des demandes de fonctionnalités pour envoyer à Google des commentaires 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 URL

Les enseignants créent souvent des devoirs avec des liens en pièces jointes. 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 votre 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'incitant à 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, indiquez à vos contacts Google les expressions régulières appropriées. Si les expressions régulières que vous fournissez sont trop larges ou en conflit avec un autre module complémentaire, elles peuvent être modifiées pour être plus restreintes ou distinctes.

Figure 1. L'enseignant sélectionne un lien joint à un nouveau devoir.

Figure 2. Un enseignant collant un lien provenant d'une source tierce L'enseignant a déjà installé le module complémentaire Classroom 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 le pop-up, comme illustré dans la figure 3, il est redirigé vers l'iFrame de découverte des pièces jointes de votre module complémentaire.