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 . Consultez les pages iFrame du répertoire Parcours utilisateur pour obtenir un aperçu de l'objectif et de l'apparence de chaque iFrame.

Consignes de sécurité pour les iFrames

Les développeurs doivent suivre les bonnes pratiques du secteur pour sécuriser leur iFrame. Toutefois, vous devez également intégrer certaines interactions API dans votre flux 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 : ceux liés aux pièces jointes et ceux 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 de l'élève et un jeton d'autorisation.

ID du cours

La valeur courseId est un identifiant du cours.

Inclus dans tous les iFrames.

ID de l'article

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

Inclus dans 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 l'une des suivantes : "announcements", "courseWork" ou "courseWorkMaterials".

Inclus dans tous les iFrames.

Identifiant de la pièce jointe

La valeur attachmentId est un identifiant de la pièce jointe.

Inclus dans les iFrames teacherViewUri, studentViewUri et studentWorkReviewUri.

ID de l'envoi

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

Inclus dans le 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 dans l'iFrame de découverte des pièces jointes et dans l'iFrame de mise à niveau des liens.

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 vers des pièces jointes de modules complémentaires pour en savoir plus.

Inclus dans l'iFrame de mise à niveau des liens .

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 difficultés de connexion de l'utilisateur final. Vous devez gérer ce paramètre de requête dans l'implémentation de votre module complémentaire.

Indication de connexion

login_hint est un identifiant unique du 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 lors de 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 :

  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 que l'utilisateur s'est connecté, utilisez ce paramètre pour comparer la valeur à tous les utilisateurs que vous avez peut-être 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 à l'aide d'un bouton de connexion de marque Google.

Inclus dans 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 des 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 sélection de 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.
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 (détermine 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 la mise à niveau des liens vers des pièces jointes de modules complémentaires est prise en charge par votre 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.
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 des liens https://example.com/upgrade. Vous avez fourni les modèles 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 mettre à niveau vers une 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. Un enseignant colle un lien, https://example.com/quiz/5678, dans la boîte de dialogue de pièce jointe de lien qui correspond à un modèle d'URL que vous avez fourni. L'enseignant est ensuite invité à mettre à niveau le lien vers une pièce jointe de module complémentaire.

  4. Classroom lance l'iFrame de mise à niveau des liens 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 CreateAddOnAttachment point de terminaison. Notez que le paramètre de requête urlToUpgrade est encodé en URI lorsqu'il est transmis sur 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 qu'une pièce jointe de module complémentaire a été 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 du host_name+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+port de la page qui envoie l'événement postMessage doit être identique à celui de l'URI utilisé pour lancer l'iFrame. Sinon, le message est ignoré. Une solution consiste à rediriger vers une page du domaine d'origine qui n'envoie que l'événement postMessage.

Fermer l'iFrame à partir d'un nouvel onglet

Les protections interdomaines empêchent cela de fonctionner. Une solution 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 postMessage de fermeture. Pour information, l'hyperlien "Ouvrir dans 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 : sandbox attributes

  • 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 propriétaire. Certains navigateurs autorisent l'accès aux cookies créés dans le contexte propriétaire lorsqu'ils se trouvent 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 dépendent pas des cookies.

D'autres restrictions concernant les cookies sont attendues dans les futures versions des navigateurs. Créez des demandes de fonctionnalités pour envoyer des commentaires à Google sur la manière de réduire l'effort 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 fréquemment 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 joint un lien correspondant à l'une de vos expressions régulières voit une boîte de dialogue qu'il peut ignorer 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 son compte.

Si vous souhaitez fournir 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 restreintes ou distinctes.

Enseignant sélectionnant une pièce jointe de lien Figure 1. Un enseignant sélectionne une pièce jointe de lien 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 découverte des expressions régulières Figure 3. La 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é à la figure 3, il est redirigé vers l'iFrame de découverte des pièces jointes de votre module complémentaire.