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 fluide et pratique. Il existe cinq types d'iframe distincts. Pour obtenir un aperçu de l'objectif et de l'apparence de chaque iframe, consultez les pages sur les iframes dans le répertoire "Parcours utilisateur".

Consignes de sécurité pour les iFrame

Les développeurs sont tenus de suivre les bonnes pratiques du secteur pour sécuriser leur iFrame. Toutefois, vous devez également intégrer certaines interactions avec l'API dans votre parcours utilisateur pour confirmer que vous disposez d'identifiants valides et que vous pouvez identifier correctement le rôle de l'utilisateur dans le cours.

Configuration de l'application serveur

Pour protéger l'iFrame, nous vous recommandons les configurations de serveur suivantes :

Paramètres de requête

Les iFrames transmettent des informations essentielles au module complémentaire sous forme de 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.

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 du module complémentaire, le devoir rendu par l'élève et un jeton d'autorisation.

ID du cours

La valeur courseId est un identifiant du cours.

Inclus avec tous les iFrames.

ID de l'article

La valeur itemId est un identifiant de Announcement, CourseWork ou CourseWorkMaterial auquel cette pièce jointe est associée.

Inclus avec tous les iFrames.

Type d'élément

La valeur itemType identifie le type de ressource auquel cette pièce jointe est associée. 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 de la pièce jointe.

Inclus avec les iFrames teacherViewUri, studentViewUri et studentWorkReviewUri.

ID de la demande

La valeur submissionId est un identifiant du devoir de l'élève, mais elle doit être utilisée en combinaison avec attachmentId pour identifier le devoir d'un devoir spécifique.

Inclus dans studentWorkReviewUri.

Jeton de module 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 avec l'iFrame Attachment Discovery et l'iFrame Link Upgrade.

URL à mettre à niveau

La présence de la valeur urlToUpgrade implique que l'enseignant a inclus une pièce jointe de lien dans le devoir et a accepté de la mettre à niveau vers une pièce jointe de module complémentaire. Si vous n'avez pas encore configuré cette fonctionnalité, consultez le guide sur la mise à niveau des liens pour ajouter des pièces jointes de modules complémentaires pour en savoir plus.

Inclus dans l'iFrame de mise à niveau de l'association.

Le paramètre de requête login_hint fournit des informations sur l'utilisateur Classroom qui consulte 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 pour réduire les frictions lors de la connexion de l'utilisateur final. Vous devez gérer ce paramètre de requête dans l'implémentation de votre module complémentaire.

Indice de connexion

login_hint est un identifiant unique pour le compte Google de l'utilisateur. 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 du même utilisateur.

Le paramètre login_hint peut être utilisé de deux manières :

  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 un flux de connexion. Si le paramètre ne correspond à aucun de vos utilisateurs connectés, invitez l'utilisateur à se connecter avec un bouton de connexion à la marque Google.

Inclus avec tous les iFrames.

iFrame de découverte des 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.
Hauteur 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 la largeur de la fenêtre lorsque la fenêtre est inférieure ou égale à 600 px de large
80 % de la largeur de la fenêtre lorsque la fenêtre est supérieure à 600 px 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 un 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. Par exemple, 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é comme pièce jointe.
  4. Classroom crée un iFrame avec l'URL src définie sur https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. L'enseignant effectue une action dans l'iFrame pour sélectionner une pièce jointe.
  5. Lorsque l'utilisateur sélectionne une 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.
Hauteur 100 % de la hauteur de la fenêtre moins 140 px pour l'en-tête supérieur
Largeur 100 % de la largeur de la fenêtre

iframe studentWorkReviewUri

Dimension Description
Obligatoire Non (indique s'il s'agit d'une pièce jointe de type activité)
URI studentWorkReviewUri
Paramètres de requête courseId, itemId, itemType, attachmentId, submissionId et login_hint.
Hauteur 100 % de la hauteur de la fenêtre 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<> La barre latérale mesure 312 px lorsqu'elle est développée et 56 px lorsqu'elle est réduite.
Dimension Description
Obligatoire Oui, si votre module complémentaire est compatible avec la conversion des liens en pièces jointes de modules complémentaires.
URI Fourni dans les métadonnées du module complémentaire
Paramètres de requête courseId, itemId, itemType, addOnToken, urlToUpgrade et login_hint.
Hauteur 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 la largeur de la fenêtre lorsque la fenêtre est inférieure ou égale à 600 px de large
80 % de la largeur de la fenêtre lorsque la fenêtre est supérieure à 600 px de large
  1. Un module complémentaire Classroom est enregistré avec un URI de mise à niveau du lien https://example.com/upgrade. Vous avez fourni les préfixes 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èces jointes de modules complémentaires :
    • L'hôte est example.com et le préfixe de chemin est /quiz.
  2. Un enseignant crée une annonce, un devoir ou un support de cours dans l'un de ses cours. Par exemple, itemId=234, itemType=courseWork et courseId=123.
  3. Un enseignant colle un lien, https://example.com/quiz/5678, dans la boîte de dialogue "Ajouter un lien" qui correspond à un 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 de l'association avec l'URL 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 appelez le point de terminaison CreateAddOnAttachment. Notez que le paramètre de requête urlToUpgrade est encodé en URI lorsqu'il est transmis à 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. Une fois la pièce jointe du module complémentaire créée à 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 ce postMessage que depuis le nom d'hôte et le 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 depuis l'iFrame

Le domaine et le port de la page qui envoie l'événement postMessage doivent être identiques à ceux de l'URI utilisé pour lancer l'iFrame. Sinon, le message est ignoré. Une solution consiste à rediriger l'utilisateur vers une page du domaine d'origine qui ne fait rien d'autre que d'envoyer l'événement postMessage.

Fermer l'iFrame à partir d'un nouvel onglet

Les protections interdomaines empêchent cela. Une solution de contournement consiste à gérer vous-même les communications entre l'iframe et le nouvel onglet, et à laisser l'iframe responsable de l'émission de l'événement de fermeture postMessage. En aparté, 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 sandbox 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 fonctionnalité suivante :

  • allow="microphone *"

Sachez que le blocage des cookies tiers rend difficile le maintien d'une session connectée dans un iFrame. Consultez https://www.cookiestatus.com pour connaître l'état actuel du blocage des cookies dans différents navigateurs. Bien sûr, ce problème n'est pas propre aux modules complémentaires Google Classroom et affecte tous les sites Web qui utilisent des iFrames tiers. Beaucoup 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 first party. Certains navigateurs autorisent l'accès aux cookies créés dans un contexte propriétaire lorsqu'ils se trouvent dans un contexte tiers.
  • Demandez à l'utilisateur d'autoriser les cookies tiers. Il est possible que cela ne soit pas toujours possible avec tous les utilisateurs.
  • Concevez des applications Web monopages qui ne dépendent pas des cookies.

D'autres restrictions concernant les cookies sont prévues dans les futures 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 détectabilité des modules complémentaires à l'aide d'expressions régulières d'URL

Les enseignants créent souvent des devoirs avec des pièces jointes de liens. Pour promouvoir l'utilisation de votre module complémentaire, vous pouvez spécifier des expressions régulières qui correspondent aux URL des ressources accessibles dans votre module complémentaire. Un enseignant qui associe un lien correspondant à l'une de vos expressions régulières voit une boîte de dialogue qu'il peut fermer et qui l'encourage à essayer votre module complémentaire. La boîte de dialogue ne s'affiche que si le module complémentaire est déjà installé pour leur compte.

Si vous souhaitez proposer ce comportement aux enseignants, fournissez les expressions régulières appropriées à vos contacts Google. 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 restrictives ou distinctes.

Enseignant sélectionnant une pièce jointe de lien Figure 1. Un enseignant sélectionne un lien en pièce jointe pour un nouveau devoir.

L&#39;enseignant colle un lien Figure 2 : Un enseignant colle un lien provenant d'une source tierce. L'enseignant a déjà installé le module complémentaire Classroom du tiers.

Boîte de dialogue de visibilité des expressions régulières 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 illustré à la figure 3, il est redirigé vers l'iFrame de découverte des pièces jointes de votre module complémentaire.